BMCLI Help and documentation contract

Reference version: BMCLI 1.6.3. Command names, parameters and machine-readable fields retain their source spelling.

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>`	On CAN, one value sets nominal=data (for example `500` means `500/500`); use `--nbitrate`/`--dbitrate` or `N/D` for different rates. LIN keeps its bps semantics.
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. Failure text is available only at error.message; bounded failure documents do not contain a duplicate top-level message.
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. Nested historical/sample errors do not change a successful query’s exit code. For example, modbus value latest/history returns 0 when the query succeeds even if a retained sample has quality=bad and sample.status=error. The sample still describes the failed measurement; a top-level query error or a top-level error record in JSONL still returns 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 four 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
Virtual name	namespaced exact BMAPI name	`virtual:Qk1BUEkgVmlydHVhbCBDaGFubmVsIEE`	Stable base64url selector; the readable BMAPI name remains in `name`
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 / and all digits → legacy numeric index
No / and non-numeric → legacy exact-name match; duplicate names fail closed

Recommendation: use the exact non-empty selector returned by channel enumerate in scripts, AI instructions, and saved bench profiles. Physical selectors are UID/port (with SN/port fallback); virtual selectors are the namespaced base64url virtual: value returned in selector, never a raw display name, synthetic /0, or internal slot number. If BMAPI exposes two indistinguishable virtual records with the same name, enumeration returns an ambiguous_channel_identity error instead of publishing duplicate selectors. Legacy numeric indexes and raw-name matching are backward-compatible, order-sensitive forms 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.

BMCLI serializes local BMAPI discovery across BMCLI processes on the same host. The coordination identity does not depend on the user or runtime directory. Only the enumeration call and its brief USB-release handoff are locked; opening a channel and using it remain independent. If another BMCLI process is still enumerating after 30 seconds, the command fails instead of returning a partial device list. The lock is released by the operating system if a process exits unexpectedly.

# 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 1.6.3 repository documentation. Run bmcli help <category> <action> --format=json for the exact contract of the installed version.