Commands

The cairn CLI surface beyond the core run/spec/authoring commands. Each page below documents one command family — flags, flow, and when to reach for it. Every command supports --format json|yaml|md and has a stable JSON schema; no interactive prompts on --json/--yaml paths.

Maintenance

• Doctor & clean — cairn doctor probes the environment; cairn clean prunes old run directories.

Page inspection

• Discover & snapshot — cairn discover / cairn snapshot return the accessibility tree and locator inventory for a live page.

Sessions

• Checkpoints & login — cairn login captures a session by hand; cairn checkpoint manages resumable checkpoints.

Evidence

• Stash — cairn stash persists run packs in the local file.cheap vault for retention-safe search.
• Clip — cairn clip cuts named clips from a run video via vidtrace.
• Process monitoring — --monitor samples the browser process tree; the monitor step and process verifier assert on it.
• Stats — cairn stats --group-by <label-key> aggregates labeled runs (cairn run --label key=value) into A/B cohorts with pass rate, duration percentiles, optional domain metrics from outcomes/*.raw.json, and ASCII charts in markdown. Pair with --before hooks for domain path flips before a suite.

Failure → code

• Investigate & audit — cairn investigate stashes an existing run for optional code search; cairn audit records a Playwright video and uses file.cheap/vecgrep only when stash or connection is requested.
• Annotate — cairn annotate pins cairntrace findings to codemap symbols; --auto-annotate does it per run.

Environment

• Secrets — cairn secrets checks the TinyVault secrets provider.
• Services — cairn services status and the config-driven docker/seed/tmux lifecycle.

The core commands

The run/spec/authoring surface is documented elsewhere and is not duplicated here:

• Quickstart — cairn run, first spec.
• Authoring — tags, labels, --before/--after hooks, cairn stats.
• Steps / Verifiers — the typed vocabularies.
• Snippets — imports: / use:.
• MCP — cairn mcp serve and the cairn_* tool family.

Run cairn explain --format json (or MCP cairn_explain) for the machine-readable current surface, including every flag.

See also

• Overview — what cairntrace is
• Configuration — config keys the commands read
• Troubleshooting — common command failure modes