CLI command reference

viewalyzer-cli <command> [flags], or viewalyzer --headless [flags] for the flag form. viewalyzer-cli help prints this list with every connection key. The binary ships inside the ViewAlyzer app package and next to it in the BKPT Debug extension; the Python SDK finds it through the VIEWALYZER environment variable, then PATH, then the install locations.

Commands

The flag form

Connection keys

The same names work as flags (--key value) and as keys in a .vacf JSON file (--config); flags win over the file. Unknown keys are errors; comment and _* keys are notes.

--elf <firmware.elf> on capture, snapshot and poll pins the control block from the image (_VA_RAMBUF, _SEGGER_RTT) instead of scanning RAM, and names the polled symbols.

Older tool-path and server-port keys (jlink, arm-gdb, *-port, stlink) are accepted and reported as "no effect": the native probe drivers spawn no servers.

Output conventions

The two lines hosts parse:

[headless] Recording saved: D:/tmp/run.vadb (2848 KB)
[headless] Recording registered: id=328d49aa4eb6

[headless] ERROR: ... precedes any failure. [headless] State: ..., [headless] t=... events ... and [capture] ... are progress, not contract.

Errors are one envelope:

{ "schema_version": 2, "error": "window_too_wide",
  "message": "634 events in the window exceed the 200 row cap for budget low",
  "suggestion": { "t_end_us": 31545, "or": "filter with --kinds, or raise --budget" },
  "limits": { "max_rows": 200, "would_return_rows": 634 } }

Codes: bad_arguments, bad_config, no_such_recording, bad_recording, window_too_wide, bad_sql, empty_capture, capture_failed, snapshot_failed, empty_snapshot, reset_failed, cooldown_active (with retry_after_s), license_file_rejected, no_hw_trace, etm_not_present, symbol_not_found, internal.

Recordings and the index

A recording is one SQLite file. Any command that takes --recording accepts a path or the 12-hex recording_id; recordings lists {recording_id, path, schema_name, duration_us, size_bytes, created_utc} for every registered file that still exists, and the id is a stable hash of the absolute path and mtime. The index lives at <app dir>/recordings/index.json (%APPDATA%\ViewAlyzer-GPUI, ~/Library/Application Support/ViewAlyzer-GPUI, ~/.config/ViewAlyzer-GPUI); hosts that manage their own files pass paths and --no-register.

Utilities in practice

$ viewalyzer-cli version
{"schema_version":2,"app":"ViewAlyzer","version":"1.1.0","core":"rust","edition":"full","transports":["stlink-swo","stlink-rambuf","stlink-rtt","jlink-swo","jlink-rtt","jlink-rambuf","udp","serial","swo-tcp"],"license":{"type":"key","tier":"solo","licensed":true}}

$ viewalyzer-cli targets --filter STM32G474
{"schema_version":2,"filter":"STM32G474","count":18,"targets":[{"name":"STM32G474CB","architecture":"arm"}, ...]}

$ viewalyzer-cli config --config nucleo_g474_rambuf.vacf --stlink-serial 0033004B3033510735393935
{"schema_version":2,"config":{"transport":"stlink-rambuf","target-device":"STM32G474RE","interface":"SWD","speed-khz":24000,"no-reset":false,"stlink-serial":"0033004B3033510735393935","rambuf-scan-start":536870912,"rambuf-scan-size":131072},"describe":"stlink-rambuf target STM32G474RE cb 0x00000000 scan 0x20000000+0x20000 reset=true","probe_spec":"stlink:0033004B3033510735393935","capture_error":null,"notes":[]}

$ viewalyzer-cli symbols --elf firmware.elf --filter uwTick
{"schema_version":2,"symbol_legend":[{"name":"uwTick","address":"0x20000058","size":4,"type":"i32"}, ...],"data_symbols":3,"text_symbols":0}

$ viewalyzer-cli memory --elf firmware.elf
{"schema_version":2,"text":6816,"data":16,"bss":11016,"total":17848,"flash_used":6832,"ram_used":11032,"sections":[{"name":".text","address":"0x080001D8","size":6056,"category":"flash"}, ...]}

$ viewalyzer-cli doctor
{"schema_version":2,"app_version":"1.1.0","checks":[{"id":"probes_stlink","status":"ok","detail":"0033004B3033510735393935"},{"id":"probes_jlink","status":"none"},{"id":"serial_ports","status":"ok","detail":"COM29"},{"id":"recordings_dir","required":true,"status":"ok","path":"..."},{"id":"probe_rs_targets","status":"ok","detail":"3891 targets"},{"id":"license","status":"ok","detail":"Active"}]}

doctor is the first thing to run on a new machine: it exits 0 whatever it finds and names what is missing.

Tests

cargo test -p va-cli runs hardware-free end-to-end tests on every OS: a synthetic recorder stream through load, every query tier and export, a UDP loopback capture with COBS framing, --stream and --stop-file, the error paths, and a loopback SWO capture through every hardware-trace query plus the hwtrace --dry-run conformance table shared with bkpt_gdbserver.