CLI reference

The cairn CLI is the control client. Run it from an installed wheel (cairn ...) or a repo checkout (uv run cairn ...). The command surface is a small, focused set of verbs.

Commands

doctor

Preflight health check. Confirms packs load, profile bindings resolve to registered operators, required services are present, the environment inventory is satisfied, and configured MCP servers are reachable. The fastest way to verify an install.

ls

Lists what each installed pack contributes — name, version, tags, code contributions (tools / executors / triggers / backends), and declared assets.

validate

Offline validation of a template / skill / policy bundle. No LLM calls.

run

Compile a namespaced template reference and run it.

cairn run training/finetune --input job.json

Flag	Effect
--input <file>	Feed the JSON file as the template’s input payload (bypasses skill matching).
--dry-run	Compile and validate only — show the plan and write a trace, without executing. Requires --input.
--mock	Operators that declare supports_mock take their mock path (no live calls).

replay

Render a past run’s trace as a human-readable timeline, read from .cairn/runs/<run_id>/ (meta.json + events.jsonl).

eval

Dataset-driven scoring for a pack’s templates. Each case is fired through the same pipeline as run.

test

Run a pack’s pytest suite — a thin wrapper that locates the pack’s tests (<path>/tests if present, else the path itself) and shells out to pytest. Arguments after -- pass straight through.

cairn test obsagent/packs/training -- -k finetune

lock

Pin the shipped pack closure by content hash, written to cairn.lock.

cairn lock            # write/update the lockfile
cairn lock --check    # recompute and fail if anything drifted (CI gate)

visualize

Render a compiled template’s graph as Mermaid (paste into any markdown tool). Today the supported view is template.

cairn visualize template training/finetune

init

Scaffolding subcommands for creating new packs and operators.

remote

Drive a running cairn server (the trigger/control plane) from your terminal over its HTTP + SSE API — submit runs, watch them live, and resolve approvals. The server protects these routes with JWT auth when OBS_JWT_SECRET is set.

cairn remote login --endpoint https://your-server   # authenticate, store a JWT
cairn remote submit <skill> -i key=value             # fire a run (async)
cairn remote ps                                      # list runs
cairn remote status <run_id>                         # one run's detail
cairn remote logs -f <run_id>                        # stream events live (SSE)
cairn remote cancel <run_id>                         # cancel a run

Human-in-the-loop (ADR-0034): a run paused at an operation gate has status awaiting_approval. Resolve it from the terminal — routed to the deployment’s runtime via POST /runs/{id}/resume:

cairn remote approve <run_id>            # approve → resume
cairn remote reject  <run_id>            # reject → skip the gated op
cairn remote approve --watch <run_id>    # stream → prompt at the pause → resume

--watch renders what’s being approved (operator, risk, sources, allowed decisions) and prompts for a single keypress. In a non-TTY (CI) it never blocks on stdin — pass --decision approve|reject, or it detaches and leaves the run paused. --timeout N --on-timeout {detach,reject,abort} bounds the wait.