CLI reference

The cairn CLI is the control client. Run it from an installed wheel (cairn ...) or a repo checkout (uv run cairn ...).

Commands fall into five groups:

Group	Commands
Inspect & verify	doctor · ls · validate · pack · config
Run & replay	run · preflight · replay · lineage · eval · test · visualize
Author	init · lock · bundle
Serve & operate	remote · worker · deploy · demo
Govern & improve	ask · connect · pilot · knowledge · suggest

Inspect & verify

doctor

Preflight health check: env config + reachability of configured services. Confirms packs load, profile bindings resolve to registered operators, and required services are present. The fastest way to verify an install.

Flag	Effect
--strict	Treat warnings as failures (exit non-zero).

ls [PACK]

List packs and their contributions — name, version, tags, code contributions, declared assets. Pass a pack name to restrict the listing; --json for a machine-readable shape.

validate PATHS...

Offline validation of templates / skills / policies. No LLM calls, no backend.

Flag	Effect
--strict	Treat warnings as failures.
--template-path <dir>	Extra directory to resolve skill template refs from (repeatable).
-v, --verbose	Verbose output.

pack schema

Emit the UI contract for a template — inputs/outputs schema, plan, steps, integrations. This is the same contract every cairn surface (CLI, console, HTTP) renders from. Exit 0 if the template is runnable.

config workflow

Show the composed configuration surface for a workflow: the knobs of every operator reachable from it, split into governance and operational scopes. See Configuration.

Run & replay

run TRIGGER_FILE

Fire one trigger (or template) through the pipeline and persist a replayable trace. Two modes:

• Trigger mode (default): the positional argument is a trigger JSON file; the payload is skill-matched and policy-gated.
• Direct-template mode (with --input): the positional argument is a namespaced template ref like training/finetune, run directly against the input JSON — no skill matching, no policy.

cairn run training/finetune --input job.json

Flag	Effect
--source <s>	Trigger source for raw payloads: pattern / alert / metric / schedule / manual / cascade. Default manual.
--service <name>	Service the trigger targets (falls back to payload.service).
--env <env>	Policy environment: dev / staging / production. Default production.
--input <file>	Direct-template mode: the template’s input payload.
--dry-run	Direct-template mode: compile + validate + show the execution plan (the node DAG) without running any operator.
--mock	Direct-template mode: operators that declare supports_mock take their .mock() path (no side effects).
-I, --interactive	Direct-template mode: at each governed HITL gate, prompt approve/reject in the terminal and resume in-process (no server needed).

preflight TEMPLATE_REF

The side-effect-free ready/blocked verdict for a workflow — cost, gates, and blockers — without starting a run. Exit 0 = ready, 1 = blocked.

cairn preflight dataset-readiness/check -i inputs.json

Flag	Effect
-i, --input <file>	JSON object of input values. Optional — with no inputs the verdict lists what’s missing.
-p, --profile <name>	Environment/profile the plan resolves under. Default: the env-default profile.
--no-connections	Skip the advisory connection-health check (faster; offline).

replay RUN_ID

Render a past run’s persisted event trace as a human-readable timeline.

Flag	Effect
--json	Emit raw meta + events JSON instead of the timeline.
--source <s>	Trace source: auto (local files, else DB store) / file / db. Default auto.

lineage [SUBJECT]

Show the content-addressed provenance/lineage record(s) for a subject — a model name, incident id, plan id (matched on the audit target / model_name / subject). Omit the subject to list all records.

Flag	Effect
--json	Emit matching records as JSON.
--audit-log <path>	Audit log path. Default: $OBS_AUDIT_LOG or ./audit.jsonl.

eval PACK

Dataset-driven evaluation for a pack’s templates. Each case fires through the same pipeline as run. Two workflows:

Regression — snapshot, change, compare:

cairn eval <pack> --save-baseline before.json
# ...edit prompts / change model...
cairn eval <pack> --compare-against before.json --threshold 80

Recipe eval — score a produced artifact against the pack’s declared eval recipe instead of running dataset cases:

cairn eval <pack> --recipe --tier easy --output run-output.json

Flag	Effect
--case <name>	Run only one case.
--dataset <stem>	Restrict to one dataset file.
--env <env>	Policy environment. Default production.
--json	Machine-readable summary.
--save-baseline <file>	Persist per-case outputs as a regression baseline.
--compare-against <file>	Compare against a baseline: per-case agreement, cost delta, template-version-change flag.
--threshold <pct>	With --compare-against: minimum agreement % to exit 0 (CI gating).
--recipe	Score a produced artifact with the pack’s eval recipe. Requires --output.
--output <file>	With --recipe: the run’s stored output JSON. Scored, never re-run.
--tier <t>	With --recipe: restrict to one demo tier (easy / medium / complex).
--workflow <name>	With --recipe: restrict to one workflow (template).
--runtime	With --recipe: run the reference-free runtime recipe instead of the .eval test recipe.
--mock	With --recipe: take the eval operator’s mock() path (no LLM/GPU/IO).

test [PACK_PATH] [PYTEST_ARGS]...

Run a pack’s pytest suite — 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 cairn/packs/training -- -k finetune

visualize KIND NAME

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

cairn visualize template training/finetune -o graph.mmd

Author

init

Scaffolding subcommands:

Subcommand	Creates
init pack	A new pack (flat layout: one dir = project = package = pack).
init template	A minimal flow: prompt template stub in the current pack.
init skill	A minimal skill stub.
init policy	A minimal policy stub.
init operator	An operator pack — a wheel bundling one or more operators.

lock

Pin the shipped pack closure by content hash into cairn.lock.

cairn lock            # write/update the lockfile
cairn lock --check    # CI gate: recompute and fail if missing or stale

bundle

Bundle-pipeline tooling. A bundle chains multiple governed workflows into a pipeline — see Pipelines & bundles.

Subcommand	Effect
bundle validate	Validate a bundle’s data contract against the participating templates’ schemas. Exits non-zero on any violation.
bundle run	Validate, compile, and run a bundle pipeline in-process; prints each step’s steps.<id> output and the final result.

Serve & operate

remote

Drive a running cairn server over its HTTP + SSE API — submit runs, watch them live, 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 (one-shot)
cairn remote watch                                  # live-refreshing dashboard
cairn remote status <run_id>                        # one run's lifecycle record
cairn remote logs -f <run_id>                       # tail events live (SSE)
cairn remote cancel <run_id>                        # cancel (best-effort)

Human-in-the-loop: a run paused at an operation gate has status awaiting_approval; resolve it from the terminal:

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

Also: remote console (interactive Textual TUI over the server; needs the tui extra) and remote hash-password (print an argon2 hash for OBS_API_PASSWORD_HASH; needs the auth extra).

worker

Run a Temporal worker for the durable runtime.

Flag	Effect
--remote	Poll the dedicated remote/GPU queue (OBS_TEMPORAL_REMOTE_TASK_QUEUE).
--task-queue <name>	Override the task queue to poll (takes precedence over --remote).

deploy

Operate the unified deployment stack (compose profiles + one .env).

Subcommand	Effect
deploy doctor	Validate that the deploy .env and enabled profiles are consistent — required vars present, runtime/profile agreement (e.g. OBS_RUNTIME=temporal needs the temporal profile). --env <file>, --profile <name> (repeatable), --strict.

demo

Seed an opt-in demo workspace — runs, a pilot, an audit trail, a pending approval — so a fresh install has something to look at.

Flag	Effect
-w, --workspace <id>	Workspace id to seed / archive. Default demo.
--archive	Tear the demo workspace down (soft-delete; runs/audit preserved).

Govern & improve

ask

AI-assisted: turn intent into governed cairn plans and runs. The assistant never bypasses policy — it produces the same governed plans you could build by hand.

Subcommand	Effect
ask plan	Assemble a deterministic plan for a template (no LLM). Exit 0 if runnable.
ask run	Resolve a natural-language intent → governed plan (LLM intent→template).

Flag	Effect
--profile <path>	Execution profile path.
--model <id>	Model for intent resolution. Default gpt-4o-mini.

connect

Manage typed infra connections — model APIs, compute, MCP servers. Secret values live in the secret store; connections hold references only.

Subcommand	Effect
connect add	Add (or --force replace) a connection from the provider catalog, or an OAuth connection via a broker (--via oauth).
connect authorize	(Re)start the OAuth flow for an existing kind=oauth connection.
connect ls	List configured connections (names + kinds + secret keys — never values).
connect test	Resolve the connection’s secret refs, run the provider’s authenticated health probe, persist the result. Exit 0 = connected / degraded-but-reachable, 1 = missing/failed.
connect rm	Delete a connection (removes the reference — never the secret value).
connect providers	List the provider catalog — what you can connect add.

pilot

The pilot evaluation ledger — pilots, experiments, runs, scorecards, findings. A pilot is a hypothesis under evaluation; experiments are its arms; runs attach to experiments with a role (cairn or baseline).

Subcommand	Effect
pilot new	Create a pilot.
pilot experiment	Add an experiment arm.
pilot attach	Attach a run to an experiment with a role (cairn | baseline).
pilot score	Record a reviewer scorecard for a run (weighted overall computed on write).
pilot baseline	Record the structured manual baseline for a run (setup/tools/commands/retries).
pilot finding	Record a finding on a pilot (optionally pinned to a run).
pilot link	Link a run out to an external system (Langfuse / Grafana / Notion…).
pilot overall	A run’s weighted overall + whether it clears the success thresholds.
pilot cohort	A run’s per-reviewer scorecards + inter-rater agreement.
pilot delta	The manual-baseline-vs-cairn glue-cut delta for a run.
pilot compare	Compare a pilot’s experiments: cairn vs baseline mean weighted overall.
pilot rollup	Aggregate scorecard + cost over a pilot’s or experiment’s run group.
pilot ls	List pilots (or one pilot’s experiments with --pilot).

knowledge

Bring-your-own knowledge corpora — git-sourced, indexed, composed into roles.

Subcommand	Effect
knowledge add	Register a git-sourced corpus (optionally index it now).
knowledge list	List registered BYO corpora.
knowledge index	Pull the source + run it through the RAG pipeline (parse → embed → upsert).
knowledge remove	Remove a BYO corpus record (vectors re-indexed away on the next pass).
knowledge index-packs	Index the RAG corpora declared by installed packs.

suggest

Governed improvement suggestions — cluster labeled failures, route, review, accept/reject. Suggestions are proposals; a human accepts or rejects them.

Subcommand	Effect
suggest generate	Cluster a workflow’s labeled failures and emit routed suggestions.
suggest list / show	Browse suggestions.
suggest accept / reject	Resolve a suggestion.