Invocation#

bash

spis capture-cli-references --plan <file.json> [--list] [--product <slug>]... [--catalog-only]

Capture the command-line products a capture plan declares in controlled real PTYs and regenerate their catalog. Nothing about a product or the terminal is compiled into Spis: the plan (spis.cli-capture-plan.v1, for example the repository's capture-plans/cli-products.json) names the catalog, its title, the terminal ("terminal": {"columns": N, "rows": N, "font_px": N, "background": "#rrggbb", "foreground": "#rrggbb"}: the pseudo-terminal size every capture runs in, the font size its PNG frames are rendered at, and the frame and text colours; each cell is the font's own advance and line height, with no margin), every product with its binary, repository, category, selection note and the version, help and subcommand forms to run, and the binaries deliberately excluded with the reason.

Inputs and options#

--plan <file.json> is required and names the capture plan. A relative path is read from the directory the command was typed in, not from the adopted corpus.
--list runs each planned product's version probe and reports what is installed, then returns without capture.
--product <slug> may be repeated to select planned products; with none, every planned product is selected.
--catalog-only performs no new PTY capture and rebuilds sources.json and references.json from the records on disk.

Output and state effects#

--list resolves and probes the planned products' version commands and prints availability, then the plan's exclusions. Normal mode records selected installed CLIs in the plan's terminal through version, help, subcommand, invalid flag, cancellation, recovery, and no-color steps; writes an asciinema cast, five deterministic screenshots and reference records under <corpus>/<plan catalog>/references/; then regenerates the catalog files, whose title and exclusions come from the plan. --catalog-only skips capture and rebuilds from retained runs. The last line names the next step: spis verify-reference-evidence --catalog <plan catalog> --apply.

Catalog regeneration derives the terminal column count from each retained recording and orientation from its overview image dimensions. Changing the plan after capture does not relabel old recordings. Missing, malformed or nonpositive dimensions refuse regeneration with the record path and the missing measurement instead of inventing an orientation or terminal size.

Refusals#

These messages are emitted by the current Rust implementation:

Without the plan: --plan is required with the usage line, exit 2; --plan requires a path and --product requires a slug when the value is missing.
Unknown input is unknown flag: VALUE followed by the usage line, exit 2.
A plan that cannot be read or parsed: read capture plan PATH: … or parse capture plan PATH: … (a plan without terminal, or a terminal without background or foreground, is refused here as missing field …); one with another schema: capture plan PATH has schema "…"; this command reads spis.cli-capture-plan.v1; one that declares no products, a product twice, a catalog that is not one directory name, a terminal with a zero column, row or font size, or a colour that is not #rrggbb, each named in the refusal.
--product X is not in PATH; it declares: a, b, … when the slug is not planned, exit 2.
If a selected executable cannot be resolved, the command refuses with not on PATH: BINARY, ... before capturing any selected product.
Catalog regeneration refuses record PATH has no positive captured terminal width, record PATH has no positive overview width, or record PATH has no positive overview height when retained evidence lacks the respective measurement. Recapture the affected product to obtain measured evidence.