BMCLI Help and documentation contract

The installed executable is authoritative for current command discovery, syntax, option names, required/default values, units, aliases, and short safety notes:

bmcli help
bmcli help device
bmcli help channel autoset
bmcli channel autoset --help
bmcli help channel autoset --format=json

Use JSON Help when an AI or script needs the exact contract of the installed version. This Reference adds detailed behavior, output schemas, protocol semantics, workflows, and extended examples; it must agree with Help but is not a second independently maintained option inventory. The Linux man page only points to local Help and this Reference and contains no independent command facts.

Common conventions:

Concept	Format	Examples
Channel	`--channel=<SPEC>`	See Channel Specification below
CAN ID	`--message=<ID>` or `--id=<ID>`	`0x123` (hex), `0x18FEDC01` (29-bit ext), `299` (decimal)
Flags	`--flags=<FLAGS>`	`fdf+brs+ide+rtr` (plus-separated)
Data	`--data=<HEX>`	`"AA BB CC DD"` (space-separated hex bytes)
Bitrate	`--bitrate=<N>`	`500`, `500K`, `500000`, and `500,000` all mean 500 kbps; `1M` and `1000000` mean 1000 kbps
Mode	`--mode=<MODE>`	`normal`, `listen-only`, `loopback`, `internal-loopback`, `external-loopback`
CAN termination	`--termination=<VAL>`	`120`, `off`
LIN pull-up	`--pullup=<VAL>`	`1k`, `off`
Channel power	`channel power <status	on

Structured output and exit contract

Use --format=json for bounded commands and --format=jsonl for streams.

A bounded JSON command writes exactly one JSON document to stdout.
Successful documents contain "status":"ok"; failed documents contain "status":"error" plus error.code, error.message, error.details, and error.retryable. A top-level message remains available for CLI consumers.
Bounded message recv --format=json returns one object with a messages array and summary fields. Use JSONL when each frame must be consumed as it arrives.
JSONL writes one object per line. Progress and warning records use an event field while retaining status; CAN receive records are independently parseable objects.
Non-fatal human notes and warnings may be written to stderr and do not corrupt JSON stdout.
Process exit code 0 means the requested command completed successfully. Exit code 1 covers usage, configuration, environment, transport, hardware, timeout, and negative UDS response failures. Inspect JSON fields such as error.code, nrc, and protocol-specific details to classify the failure instead of relying on additional exit-code values.
A successful inspection can report a domain state such as DEGRADED; a validation with missing required values reports status=error and exits 1.

Existing fields keep their meaning within a major product version. New fields may be added, so consumers must ignore unknown members. CAN IDs are hexadecimal strings, booleans are JSON booleans, and units are carried in field names such as _kbps, _ms, and _seconds.

Channel Specification

The --channel parameter supports three forms:

Form	Syntax	Example	Description
SN/port	`SN/PORT`	`10356/0`	Device serial number + port number
UID/port	`UID/PORT`	`423BAE5191B9/0`	Device UID (12 alphanumeric characters) + port number
Legacy	`N`	`0`, `0,1`, `0-3`	Enumerate index (backward compatible)

Auto-detection rules (for the part before /):

Alphanumeric, length 12 → UID
All digits, length 4-6 → SN
No / found → legacy numeric index

Recommendation: use SN/port in scripts, AI instructions, saved bench profiles, and customer documentation. A legacy numeric index is suitable only for short-lived interactive work after inspecting the current enumeration result.

Why SN/port? USB enumeration order is OS-dependent — the same device may appear at different indices across BM_Enumerate() calls. SN/port identification ensures deterministic device selection regardless of enumeration order.

# Open specific device by SN + port
bmcli daemon start --channel=10356/0,10356/1
bmcli channel open --channel=10356/0 --nbitrate=500k

# Multi-device: open ports on different devices
bmcli daemon start --channel=10356/0,10357/0

# Legacy (still supported, order-dependent)
bmcli daemon start --channel=0,1

Source of truth: bmcli_reference.md in the BMCLI repository. Run bmcli help <category> <action> --format=json for the exact contract of the installed version.