Command Reference

L0 Command Reference

I use this as my complete command-line reference for l0c in the current v1 toolchain.

Command Model

I keep CLI behavior deterministic:

• success path prints stable text output (ok, metadata lines, or run result)
• failure path uses stable usage: ... or error: ... forms
• exit-code/error class stability is frozen in docs/ERROR_MODEL.md

canon

Canonicalize a module and emit canonical source.

Forms:

• ./bin/l0c canon <module.l0>
• ./bin/l0c canon <module.l0> -o <out.l0>

Success example:

./bin/l0c canon tests/valid_min.l0 -o /tmp/min.canon.l0

Failure example:

./bin/l0c canon tests/invalid_order.l0

Expected class: error: invalid module shape or non-canonical input.

verify

Parse and verify canonical module validity.

Form:

• ./bin/l0c verify <module.l0>

Success example:

./bin/l0c verify tests/valid_min.l0

Failure example:

./bin/l0c verify tests/invalid_order.l0

Expected class: error: invalid module shape or non-canonical input.

build

Build L0 source to L0 image, optionally emitting debug-map and trace-schema side artifacts.

Forms:

• ./bin/l0c build <module.l0> <out.l0img>
• ./bin/l0c build <module.l0> -o <out.l0img>
• ./bin/l0c build <module.l0> <out.l0img> --debug-map <out.map> --trace-schema <out.schema>

Success example:

./bin/l0c build tests/valid_trace_noop.l0 /tmp/trace.img \
  --debug-map /tmp/trace.map \
  --trace-schema /tmp/trace.schema

Failure example:

./bin/l0c build /tmp/no_such_file.l0 /tmp/out.img

Expected class: error: cannot open input.

build-elf

Build L0 source to ELF64 relocatable object output.

Form:

• ./bin/l0c build-elf <module.l0> <out.o>

Success example:

./bin/l0c build-elf tests/valid_sysv_abi_sum6_lowered.l0 /tmp/sum6.o

Failure example:

./bin/l0c build-elf /tmp/no_such_file.l0 /tmp/sum6.o

Expected class: error: cannot open input.

imgcheck

Validate L0 image container integrity and schema constraints.

Form:

• ./bin/l0c imgcheck <file.l0img>

Success example:

./bin/l0c imgcheck /tmp/trace.img

Failure example:

printf 'BADIMG' >/tmp/bad.img && ./bin/l0c imgcheck /tmp/bad.img

Expected class: error: invalid or corrupt L0IMG.

imgmeta

Print stable decoded metadata for a valid L0 image.

Form:

• ./bin/l0c imgmeta <file.l0img>

Success example:

./bin/l0c imgmeta /tmp/trace.img

Failure example:

printf 'BADIMG' >/tmp/bad.img && ./bin/l0c imgmeta /tmp/bad.img

Expected class: error: invalid or corrupt L0IMG.

run

Execute code payload from L0 image and print returned u64 value.

Form:

• ./bin/l0c run <file.l0img> [u64_a] [u64_b] [u64_c] [u64_d] [u64_e] [u64_f]

Success example:

./bin/l0c run /tmp/trace.img 123

Failure example:

./bin/l0c run /tmp/trace.img not_a_u64

Expected class: error: invalid run argument (expected unsigned decimal).

tracecat

Decode binary trace records into stable text output.

Form:

• ./bin/l0c tracecat <trace.bin>

Success example:

./bin/l0c tracecat /tmp/trace.bin

Failure example:

printf '\x01' >/tmp/truncated.trace && ./bin/l0c tracecat /tmp/truncated.trace

Expected class: error: invalid module shape or non-canonical input.

mapcat

Decode debug-map payload into stable text output.

Form:

• ./bin/l0c mapcat <debug_map.bin>

Success example:

./bin/l0c mapcat /tmp/trace.map

Failure example:

printf 'BAD!' >/tmp/bad.map && ./bin/l0c mapcat /tmp/bad.map

Expected class: error: invalid module shape or non-canonical input.

schemacat

Decode trace-schema payload into stable text output.

Form:

• ./bin/l0c schemacat <trace_schema.bin>

Success example:

./bin/l0c schemacat /tmp/trace.schema

Failure example:

printf 'BAD!' >/tmp/bad.schema && ./bin/l0c schemacat /tmp/bad.schema

Expected class: error: invalid module shape or non-canonical input.

tracejoin

Join trace records against debug-map entries and print correlated output.

Form:

• ./bin/l0c tracejoin <trace.bin> <debug_map.bin>

Success example:

./bin/l0c tracejoin /tmp/trace.bin /tmp/trace.map

Failure example:

./bin/l0c tracejoin /tmp/no_trace.bin /tmp/no_map.bin

Expected class: error: cannot open input.

Related References

• error model: docs/ERROR_MODEL.md
• workflows: docs/WORKFLOWS.md
• binary/trace schema contracts: docs/DEBUG_MAP_SCHEMA.md, docs/TRACE_SCHEMA.md