canair captures¶
Alias: cap
usage: canair captures [-h] <kind> ...
[UDS+CAN] Query captured data. Choose a kind:
uds diagnostic UDS payloads (captures/*.json) — the QUERY/diff/step/
summary/sessions/latest/recover surface (domain A)
can imported raw broadcast-CAN frame logs (captures/can/index.yaml,
domain B)
A bare `canair captures BMS 2102` (or any of the --summary/--sessions/… flags) is shorthand for `canair captures uds …`.
positional arguments:
<kind>
uds Query captured diagnostic UDS payloads across all
capture files
can List imported raw broadcast-CAN frame logs
(captures/can/index.yaml)
migrate Convert legacy captures/*.yaml to JSON (captures/*.json)
migrate-rx Rename the legacy capture `ecu` field to `rx`
(captures/*.json)
migrate-discover Repair legacy discover captures: record each responder's
probed TX
split-batched Split multi-DID replies stored whole under one DID into
per-DID captures
compact Rewrite capture files with repeated polls folded, one
capture per line
purge-sensitive Remove stored replies to sensitive PIDs from capture
files
migrate-variants Tag untagged capture sessions with the profile variant
they came from
merge-driver Git merge driver: auto-union capture-file sessions (or
--install it)
options:
-h, --help show this help message and exit
canair captures uds¶
usage: canair captures uds [-h] [--diff | --step] [--summary | --sessions |
--latest | --recover | --delete |
--backfill-states | --backfill-state-spans |
--set-state STATES | --set-notes TEXT |
--set-transport NAME | --set-variant ID]
[--discard] [--overwrite] [--cycle-tol SECONDS]
[--dry-run] [--yes] [--all] [--limit N] [--rulers]
[--notation NAME]
[--view {auto,stacked,signals,changed,interleaved}]
[--join-tol SECONDS] [--json] [--since WHEN]
[--until WHEN] [--date YYYY-MM-DD] [--today]
[--last-sessions [N]] [--last-session]
[--state STATE] [--label SUBSTR] [--dir DIR]
[QUERY ...]
Query captured UDS payloads.
positional arguments:
QUERY ECU/PID selection: 'BMS 2102', 'BMS:2102,2103', 'BMS'
(all PIDs), or a quoted cross-ECU query 'VCU:2101
BMS:2101'
options:
-h, --help show this help message and exit
--diff, -d Monitor-style view (decoded signals + colored byte-
diff), one block per ECU+PID
--step, -S Interactively step through matching captures (arrow
keys; a several-PID QUERY stacks them time-joined for
cross-comparison; e=note, d=delete, ?=help)
--summary, -s Overview statistics
--sessions, -n List sessions with their metadata
(date/state/label/notes/ECUs) — a searchable table of
contents; no payloads. Shows the latest --limit
sessions. Honors the scope filters.
--latest, -l Latest payload per PID (ECU/PID taken from the QUERY,
e.g. `BMS --latest`)
--recover Reconcile orphaned capture journals (from a
killed/crashed session) into capture files. Add
--discard to delete them without saving.
--delete Delete the captures matching QUERY (and any scope
filters). Previews with --dry-run; confirms before
deleting unless --yes.
--backfill-states Infer each session's vehicle_states from its decoded
captures and fill sessions that have none. Reports
conflicts (never writes them unless --overwrite).
Previews with --dry-run; confirms unless --yes. Honors
the scope filters.
--backfill-state-spans
Reconstruct WHEN each state held during a session (a
state_spans timeline) so analysis resolves a capture's
state at its own timestamp instead of the session-wide
union. Only narrows states the evidence can place in
time. Previews with --dry-run; confirms unless --yes.
--set-state STATES Manually set vehicle_states (comma-separated) on the
scope-selected sessions — for a state known from the
label but not inferable from the data (e.g. --set-
state ACC --label 'ACC only'). Requires a scope filter
(--label/--date/--since/…); previews with --dry-run,
confirms unless --yes.
--set-notes TEXT Replace the session notes on the scope-selected
sessions — to correct a note after recording (''
clears it). Requires a scope filter
(--label/--date/--since/…); previews with --dry-run,
confirms unless --yes.
--set-transport NAME Correct the recorded transport (slcan-tcp, wican-ws,
elm327-tcp, import) on the scope-selected sessions —
for a session saved with the wrong one ('' clears it).
Requires a scope filter; previews with --dry-run,
confirms unless --yes.
--set-variant ID Tag the scope-selected sessions with the profile
variant the recorded car is (a variants.yaml ID; ''
removes the tag), attributed 'asserted'. Requires a
scope filter — the global --variant untagged selects
every untagged session; previews with --dry-run,
confirms unless --yes.
--discard With --recover: delete orphaned journals without
saving them
--overwrite With --backfill-states: also rewrite sessions whose
recorded states conflict with / differ from the
inferred states (default: fill empty only). With
--backfill-state-spans: also replace live-observed
timelines
--cycle-tol SECONDS With --backfill-states/--backfill-state-spans: max
timestamp gap grouping captures into one pseudo-cycle
for cross-ECU predicates (default 10s)
--dry-run With --delete/--backfill-states/--backfill-state-spans
and the --set-* editors: preview the changes, write
nothing
--yes, -y With --delete/--backfill-states/--backfill-state-spans
and the --set-* editors: skip the confirmation prompt
(scripting)
--all, -a For --diff/--step: use every payload instead of
unique-only
--limit, -L N Default list view: show only the most recent N
captures (default 50; 0 = no cap). With --sessions:
the most recent N sessions. A loud footer reports any
hidden history. Also caps the frames rendered by a
piped/--json --step.
--rulers, -r For --diff/--step: show the byte-index ruler above the
hex (in the notation from --notation /
display.byte_notation)
--notation NAME byte-index notation for output labels: wican
(default), isotp, torque, bix. Overrides the
display.byte_notation config key.
--view {auto,stacked,signals,changed,interleaved}
For --step: how a frame is rendered — stacked (one
block per PID), signals (signals only), changed (only
signals that moved), interleaved (one capture per
frame). Default auto: stacked for up to 6 PIDs, else
interleaved. Cycle it live with V.
--join-tol SECONDS For --step: max timestamp difference when joining
captures of different PIDs into one stacked frame
(default 10s, sized for a full round-robin monitor
cycle; adjustable live with J)
--json Machine-readable JSON output
(summary/sessions/latest/diff/step and the default
QUERY list)
--dir DIR Captures directory (default: active profile)
scoping:
Restrict to captures within a date/time range (inclusive) and/or by session state (token-matched) or label substring. --since/--until accept a date (YYYY-MM-DD) or a timestamp (YYYY-MM-DD HH:MM[:SS[.ffffff]])
--since WHEN Only captures on or after this date/time (YYYY-MM-DD[
HH:MM:SS])
--until WHEN Only captures on or before this date/time (YYYY-MM-DD[
HH:MM:SS])
--date YYYY-MM-DD Only captures on this exact date (shorthand for
--since X --until X)
--today Only captures recorded today (shorthand for --date
<today>)
--last-sessions [N] Only the most recent N recorded sessions in scope (N
defaults to 1)
--last-session Only the most recent recorded session in scope (alias
for --last-sessions 1)
--state STATE Only captures recorded in STATE, matched by token and
widened by the profile's implies: hierarchy (--state
ready also matches DRIVING). Comma-separate
alternatives (--state ready,driving); repeat the flag
to require several at once (--state charging --state
parked)
--label SUBSTR Only captures whose session/capture label contains
SUBSTR (case-insensitive)
Query captured UDS payloads across all capture files.
QUERY selects the ECU(s) and PID(s) to show (see the mini-language below).
By default the matching captures are listed (most recent --limit, default 50);
add --diff or --step to change how they are rendered. --summary and --sessions
are aggregate modes that take no QUERY.
QUERY List matching captures (default view; latest --limit)
QUERY --diff Monitor-style view (decoded signals + colored byte-diff),
one block per ECU+PID (unique payloads only; --all = all)
QUERY --step Interactive: step through captures with arrow keys,
decoded signals + byte-diff vs the previous capture of the
same PID; e adds/edits a note, d deletes a capture.
A QUERY selecting SEVERAL PIDs stacks them underneath
each other in one time-joined frame (--join-tol), so
they can be cross-compared; PIDs, tolerance and view are
all editable inside the TUI (a/t/V), s jumps between
sessions and noted captures, ? for help
QUERY --latest Most recent payload per PID for the QUERY selection
--latest Most recent payload per PID (all ECUs; no QUERY)
QUERY --delete Delete the captures matching QUERY (and scope filters);
--dry-run previews, confirms before deleting unless --yes
--set-state STATES Set vehicle_states on the scope-selected sessions
--set-notes TEXT Replace the notes on the scope-selected sessions ('' clears)
--set-transport NAME Correct the recorded transport of the scope-selected sessions
--set-variant ID Tag the scope-selected sessions with the car's variant
--summary Overview: captures per ECU, per date, total payloads
--sessions Session table of contents: date/time-span/state/label/
notes/ECUs per session (no payloads; latest --limit);
--json for machine output. Honors the scope filters.
Step views (--view; default auto — stacked for up to 6 PIDs, else interleaved):
stacked One block per PID per frame: signals + byte-diff hex
signals Params only (no hex) — fits more PIDs on one screen
changed Only signals whose decoded value moved, per block
interleaved One capture per frame, chronologically across the PIDs
Output size (default list view and --sessions):
--limit N Show only the most recent N captures, or with --sessions
the most recent N sessions (default 50; 0 = no cap). A
loud footer reports any hidden history — use --limit 0
or a tighter scope (--since/--last-session) to see the
rest.
QUERY mini-language (see src/canair/query/__init__.py):
ECU PID one PID (bare ECU + PID) e.g. BMS 2102
ECU all PIDs for an ECU e.g. VCU
ECU:PID one PID e.g. VCU:2101
ECU:PID,PID several PIDs e.g. VCU:2101,22BC03
"ECU:PID ECU:PID" cross-ECU (quote the space) e.g. "VCU:2101 BMS:2101"
ECU:22 prefix PID match (22xxxx) e.g. BCM:22
ECU:BC03 suffix PID match (->22BC03) e.g. IGPM:BC03
Date scoping (inclusive, YYYY-MM-DD; combines with any mode):
--since DATE captures on or after DATE
--until DATE captures on or before DATE
--date DATE captures on DATE only (--since DATE --until DATE)
State/label scoping (state by token, label by substring; combines with any mode):
--state SUBSTR only sessions whose vehicle_states contain SUBSTR (e.g. driving)
--label SUBSTR only sessions/captures whose label contains SUBSTR
Examples (a bare `canair captures …` is shorthand for `canair captures uds …`):
canair captures uds BMS 2102 # ECU + PID (most useful)
canair captures uds BMS # All BMS captures
canair captures uds "BMS:2102,2103" # Several PIDs
canair captures uds IGPM 22BC03 --diff # Byte-diff for one ECU+PID
canair captures uds "BMS:2102,2103" --diff # Byte-diff, one block per PID
canair captures uds BMS 2102 --step # Step through one PID
canair captures uds "BMS:2102,2103" --step # Stack two PIDs, time-joined
canair captures uds "HVAC:220100,2201A0,2201A2" --step # Cross-compare three PIDs
canair captures uds "VCU:2101 BMS:2101" --step # Cross-ECU compare
canair captures uds "VCU:2101 BMS:2101" --step --join-tol 1.0 # Tighter join
canair captures uds "HVAC:220100,2201A0" --step --view signals # Params only
canair captures uds BMS --step --view interleaved # Browse every BMS PID
canair captures uds "BMS:2102,2103" --step --json --limit 5 # Frames as data
canair captures uds --diff VCU:2101 --all # One PID, every payload
canair captures uds --summary # Overview stats
canair captures uds --sessions # Session table of contents
canair captures uds --sessions --state driving # Index of every drive
canair captures uds --sessions --json # Machine-readable TOC
canair captures uds BMS --latest # Latest payload per BMS PID
canair captures uds --latest # Latest payload per PID (all ECUs)
canair captures uds OBC 2101 --delete --dry-run # Preview a delete
canair captures uds OBC 2101 --delete --yes # Delete (non-interactive)
canair captures uds --set-notes 'Car off.' --label sweep --dry-run # Fix a note
canair captures uds BMS 2102 --limit 200 # Widen the default 50-row cap
canair captures uds BMS 2102 --limit 0 # Every matching capture (no cap)
canair captures uds --summary --since 2026-04-19 # Stats since a date
canair captures uds BMS 2101 --diff --date 2026-04-19 # One day only
canair captures uds VCU --since 2026-04-14 --until 2026-04-21 # Range
canair captures can # List imported raw broadcast-CAN frame logs
canair captures can¶
usage: canair captures can [-h] [--json]
List imported raw broadcast-CAN frame logs (domain B) — file/format/frames/IDs per log. Import them with `canair import can`.
options:
-h, --help show this help message and exit
--json Machine-readable JSON output
canair captures migrate¶
usage: canair captures migrate [-h] [--dry-run] [--json] [--dir DIR]
Convert the active profile's legacy per-day capture files (captures/YYYY-MM-DD.yaml) to JSON (captures/YYYY-MM-DD.json).
Capture data is stored as JSON (parses ~60x faster than YAML); this is the supported one-time migration for a profile created before the cutover. Each file is round-trip verified before the YAML is replaced. Performs the migration by default; pass --dry-run to preview.
options:
-h, --help show this help message and exit
--dry-run Preview conversions without writing
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures migrate-rx¶
usage: canair captures migrate-rx [-h] [--dry-run] [--json] [--dir DIR]
Rename the persisted capture field `ecu` → `rx` in the active profile's capture files.
The field holds the ECU CAN *response* address (the ECU's rx_id, else request TX + the profile's rx_offset), not an ECU name, so it was renamed to `rx` to stop it being confused with the resolved short name. Renames at the capture level and inside scan_results.responding[]; idempotent (a file already on `rx` is left untouched). Readers tolerate the legacy `ecu` key, so this migration is safe to defer. Performs the rename by default; pass --dry-run to preview.
options:
-h, --help show this help message and exit
--dry-run Preview renames without writing
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures migrate-discover¶
usage: canair captures migrate-discover [-h] [--dry-run] [--json] [--dir DIR]
Give legacy discover captures each responder's probed `tx`, and the `rx` the profile's addressing gives it.
Those captures stored only an `rx` per responder, and for an address not in the ECU registry it was computed as TX + 0x08 whatever the profile's addressing: block said. The TX is recoverable exactly: a registered responder was labelled `NAME (status)`, an unregistered one with the bare status. Idempotent; a responder whose ECU name no longer resolves (or is ambiguous) is reported, not guessed (exit 1), and a layered profile's read-only base is refused (exit 1). The session transport cannot be recovered this way — use `captures uds --set-transport`. Performs the repair by default; pass --dry-run to preview.
options:
-h, --help show this help message and exit
--dry-run Preview repairs without writing
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures split-batched¶
usage: canair captures split-batched [-h] [--dry-run] [--json] [--dir DIR]
Find service-22 captures whose payload is a whole multi-DID reply (62 D1 <data> D2 <data> …) stored under its first DID, and replace each with one capture per DID at the same time.
A batched reply starts like a single reply to its first DID, so a batch reply that leaked into a per-DID read passed the echo check and was saved whole; `validate captures` reports these. A row is split only when it walks exactly through DIDs of the same ECU at each DID's established length, so a padded or merely long reply is left alone. The split rows drop `elapsed_ms` (one round trip answered them all). In a session recorded with a dedup keep mode (`--keep-changes`, or the legacy keep:unique), a part the session would not have stored (an unchanged value) is left out and reported as unchanged. Idempotent; a layered profile's read-only base is reported, not rewritten, and so is an overlay session the base holds identically (exit 1). A missing --dir is an error (exit 2). Performs the split by default; pass --dry-run to preview.
options:
-h, --help show this help message and exit
--dry-run Preview splits without writing
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures compact¶
usage: canair captures compact [-h] [--dry-run] [--json] [--dir DIR]
Rewrite the active profile's capture files (captures/*.json) in the compact on-disk form.
A poll that repeats the previous payload of the same ECU and PID is stored as a millisecond gap on the run's first capture (`repeat_ms` / `repeat_inline_ms`), and each capture is one line. Lossless: loading expands every repeat back into its own capture, so every command sees the same data. Every write already uses this form, so this only converts files no command has rewritten since. Idempotent; each file is verified before it is replaced, and a layered profile's read-only base is refused (exit 1). Performs the rewrite by default; pass --dry-run to preview.
options:
-h, --help show this help message and exit
--dry-run Preview without writing
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures purge-sensitive¶
usage: canair captures purge-sensitive [-h] [--dry-run] [--yes] [--json]
[--dir DIR]
Remove every stored reply to a PID or signal marked `sensitive: true` (see `canair pids set-sensitive`) from the active profile's capture files.
No command saves such a reply, but a PID marked sensitive after it was recorded still has history on disk: analyses already leave it out, `validate captures` reports it, and this removes it. A session left with no capture is dropped. A layered profile's read-only base is refused (exit 1). Asks before writing unless --yes; --dry-run previews.
options:
-h, --help show this help message and exit
--dry-run Preview without writing
--yes, -y Do not ask for confirmation
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures migrate-variants¶
usage: canair captures migrate-variants [-h] [--date YYYY-MM-DD]
[--since YYYY-MM-DD]
[--until YYYY-MM-DD] [--label LABEL]
[--dry-run] [--json] [--dir DIR]
ID
Tag the active profile's untagged capture sessions with the variant (a variants.yaml ID) of the car that recorded them, attributed 'migrated'.
For history recorded before the profile declared its variants. Scope it to the sessions you know came from that car with --date/--since/--until/--label, and run it once per car. Sessions that already carry a variant are never touched, and only the profile's own captures are written (a layered profile's base is left alone). Writes by default; --dry-run previews. To correct a tag afterwards, use `captures uds --set-variant`.
positional arguments:
ID The variant the recorded car is (e.g. 28kwh)
options:
-h, --help show this help message and exit
--date YYYY-MM-DD Only this day
--since YYYY-MM-DD Only on or after this day
--until YYYY-MM-DD Only on or before this day
--label LABEL Only sessions whose label contains this text
--dry-run Preview without writing
--json Machine-readable JSON output
--dir DIR Captures directory (default: active profile)
canair captures merge-driver¶
usage: canair captures merge-driver [-h] [--install] [--json]
[base] [ours] [theirs] [path]
Git merge driver for append-only capture files (captures/*.json).
Invoked by git during a merge as `merge-driver %O %A %B %P`; unions the
session lists so two machines' same-day appends merge cleanly instead of
conflicting. Writes conflict markers into the file on a genuine divergent
edit.
Run `canair captures merge-driver --install` once per clone to register it
in .git/config (git never loads a driver command from a tracked file, so
this local step is required; until then git uses its own line-based merge).
positional arguments:
base git %O — common ancestor version
ours git %A — our version (also the output file)
theirs git %B — their version
path git %P — merged file's pathname (for messages)
options:
-h, --help show this help message and exit
--install Register the driver in this repo's .git/config (one-time, per
clone)
--json Machine-readable JSON output