CLI Reference

The labwired command-line interface is the primary entry point for running simulations, testing, and managing assets.

Global Options

These options apply to the interactive runner and most subcommands.

Option	Description
--trace	Enable instruction-level execution tracing (prints every executed instruction).
--json	Output errors and diagnostics as structured JSON for agent consumption.
--vcd <PATH>	Output a Value Change Dump (VCD) trace file to the specified path.
--rtt	Emit SEGGER RTT output: interactive runs echo drained up-channel bytes and write stdin into down-channel 0 (SEGGER_RTT_GetKey); test captures up-channel bytes to rtt.log and enables rtt_contains.
--version	Print version information.
--help	Print help message.

Modes & Commands

Interactive / Run Mode (Default)

Executes a firmware simulation interactively. If no subcommand is provided, this mode is used.

labwired --firmware <ELF> --system <YAML> [OPTIONS]

Options: - --firmware <PATH>: Path to the ELF binary to load (Required). - --system <PATH>: Path to the System Manifest YAML (Required). - --max-steps <N>: Stop simulation after N instructions (default: 20000). - --gdb <PORT>: Start a GDB RSP server on the specified port (e.g., 3333). - --breakpoint <ADDR>: Breakpoint PC address (decimal or 0xHex). Repeatable. - --snapshot <PATH>: Write a state snapshot (JSON) upon exit.

test

Runs a CI-friendly test script with assertions.

labwired test --script <YAML> [OVERRIDES]

Options: - -c, --script <PATH>: Path to the test script (see Test Runner). - -f, --firmware <PATH>: Override the firmware path in a single-machine script only; environment topology comes from inputs.env. - -s, --system <PATH>: Override the system manifest in a single-machine script only; environment topology comes from inputs.env. - --output-dir <PATH>: Directory for result.json, snapshot.json, uart.log, rtt.log, and junit.xml; requested trace, fault-evidence, coverage, and run-manifest artifacts are written there too. - --junit <PATH>: Path to write JUnit XML report. - --max-steps <N>: Override default step limit. - --max-cycles <N>: Override cycle limit. - --max-uart-bytes <N>: Override UART output limit. - --no-progress <N>: Fail if PC doesn't change for N steps (detects hangs). - --coverage: Collect firmware coverage (lines, branches, functions, with counts) from the unmodified ELF; writes coverage.info (LCOV), coverage.cobertura.xml and coverage.json. See Firmware coverage. - --no-uart-stdout: Disable echoing UART output to the console. - --max-vcd-bytes <N>: Limit the size of the generated VCD file.

coverage merge

Merge firmware-coverage LCOV files (from test --coverage, gcov, llvm-cov) into one report and list every branch the tests never took. Worked example and CI setup: Firmware coverage.

Options: - <INPUT>...: LCOV files, or directories searched recursively for *.info (earlier merge results are skipped). - -o, --output <PATH>: Merged LCOV tracefile. - --cobertura <PATH>: Cobertura XML for GitLab / Jenkins / Azure DevOps. - --source-root <DIR>: Cobertura <source> (repeatable, default .). - --json-out <PATH>: Summary, per-file numbers and uncovered branches as JSON. - --fail-under-lines <PCT>, --fail-under-branches <PCT>: Exit code 1 below the threshold.

labwired coverage with no subcommand prints the ESP32-S3 register-model coverage matrix (--svd, --json-out).

asset

Utilities for managing LabWired assets (SVD import, Code Generation, etc.).

labwired asset <SUBCOMMAND>

Subcommands: - import-svd: Import an SVD file and convert it to Strict IR (JSON). - -i, --input <SVD>: Input SVD file. - -o, --output <JSON>: Output JSON file. - codegen: Generate Rust code from Strict IR. - -i, --input <JSON>: Input IR file. - -o, --output <RS>: Output Rust source file. - init: Initialize a new project skeleton. - -o, --output <DIR>: Output directory. - -c, --chip <NAME>: Chip name to base the project on. - add-peripheral: Add a peripheral to an existing chip descriptor. - -c, --chip <YAML>: Target chip descriptor. - --id <NAME>: New peripheral ID. - --base <ADDR>: Base address. - --ir-path <PATH>: Path to IR descriptor. - validate: Validate a System Manifest and its referenced Chip. - list-chips: List available chip descriptors.

machine

Machine state control operations.

Subcommands: - load: Load a machine state from a snapshot and resume simulation. - -s, --snapshot <JSON>: Path to snapshot file. - --max-steps <N>: Override step limit. - --trace: Enable tracing.

Environment Variables

• RUST_LOG: Controls logging level (e.g., info, debug).
• Native logging uses tracing.
• Example: RUST_LOG=labwired_core=debug