CLI reference

One binary, no runtime dependencies — install with the one-line script in Getting Started. This page is the complete reference for every public subcommand: flags, defaults, and exit codes, with a link to the guide page that covers each area in depth.

Getting started

chidori demo

Interactive picker over the bundled example agents, run in the trusted posture. It resolves examples/agents/*.ts relative to the repo root, so it works only from a repo checkout. The hello, tool-use, and input-pause demos need no provider key; without one, the others print sign-in guidance and exit 0. No flags.

chidori model-login

Zero-setup provider sign-in: a browser OAuth flow against OpenRouter. The key is saved to ~/.chidori/credentials.json and used automatically whenever no ANTHROPIC_API_KEY / OPENAI_API_KEY is configured. No flags.

chidori init [dir]

Scaffold a starter project. Refuses to overwrite existing files.

These are scaffold templates — project starting points. The unrelated prompt-template host function chidori.template is covered in Prompt Templates.

chidori chat [agent.ts]

Interactive multi-turn REPL backed by conversation() (see Core Concepts). With no file, it chats with the model directly; with an agent file, it chats through the agent — the file must accept { messages, system?, model?, tools? } and return { transcript } (or { history }). Each turn is a durable host call; prior turns replay from the journal, so only the newest message reaches the provider.

chidori check <agent.ts>

Validate an agent file without running it. No flags. Exits 2 on failure — the only command that does.

Running

chidori run <agent.ts>

One-shot run, journaled under .chidori/runs/<run_id>/ next to the agent file. Walkthrough: Getting Started.

chidori dev <agent.ts>

Edit-and-replay loop: records one run, then watches the agent and re-runs on every save, replaying recorded calls from the journal — so edits cost zero tokens for everything the recording answers. Flags: -i/--input, --model, --untrusted / --trusted. See Replay & Resume.

chidori serve [agent.ts]

HTTP session server: sessions, pause/resume, signals, approvals, SSE streaming. A session is a served run — a session id is a run id. With no agent file it hosts only the detached-agent fleet re-armed from .chidori/runs/, and each session request must name an agent. Endpoint reference: Running Modes; fleet: Detached Agents; production checklist: Deployment.

Packages

See Package Management.

Replay & testing

chidori resume <agent.ts> <run_id>

Replay a recorded run byte-for-byte with zero model calls; a run that ended at a pause or crash replays to the frontier of its journal and continues live. The model recorded in the run manifest applies automatically. Concept and divergence rules: Replay & Resume.

resume --ci exits 0 on a clean match, 3 on divergence, 1 on error, and always prints a JSON report: run_id, checkpoint_path, calls_expected, calls_replayed, live_cost_usd, recorded token counts, output, status, and on divergence a divergence.kind of source_changed, missing_call, changed_call, or extra_call. It ignores --model, --untrusted/--trusted, --until-seq, and --retry-failed.

chidori verify <agent.ts> <run_id>

Replay-as-test for CI: replays with an empty provider registry, an empty tool registry, and the untrusted profile, and requires the run to complete with byte-identical output — there is no --allow-source-change escape. Journaled top-level workspace writes do re-materialize to real disk (same bytes, fresh mtime). Exits 0 on pass and 1 on any failure — no separate divergence code, unlike resume --ci — with a distinct message per failure mode (source drift, unclean replay, a pause instead of completion, output mismatch, unexpected live calls). Contract details: Replay & Resume.

chidori export <run_id> --fixture <dest>

Copy just the four artifacts verify reads — records.jsonl, runtime.snapshot.json, output.json, input.json — into <dest>/<run_id>/: the fixture you commit for CI. --fixture is required; -d/--dir defaults to the current directory.

chidori checkpoint export|import

Whole-run archives. checkpoint export <run_id> writes <run_id>.chidori-run.tar.gz (-o/--output overrides the name, -d/--dir); checkpoint import <archive> unpacks under <dir>/.chidori/runs/.

Inspection

--dir defaults differ: resume and verify default to the agent file's parent directory; the inspection and recovery commands (trace, snapshot, history, stats, export, checkpoint, branches, holdings, rollback) default to the current directory.

Branching & recovery

Branches: Branching Execution. Compensations: Host API.

Storage & deploy

chidori cell-store

Run the shared run-store server. Point CHIDORI_RUN_STORE=http://host:9700 at it and nothing else changes; CHIDORI_RUN_STORE_TOKEN adds bearer auth. See Durable Storage.

chidori deploy

Deploy an agent directory to a Chidori Deploy server (URL via --url / CHIDORI_DEPLOY_URL) — a self-hosted, experimental service, as the default http://localhost:8090 URL suggests. The model is Val-Town-style: a local directory kept in sync with the server, where each push becomes an immutable version and exactly one version is live. With no subcommand, chidori deploy pushes the current directory as a new live version.

Configuration resolves per field as CLI flag → environment → ~/.chidori/credentials.json:

• URL: --url → CHIDORI_DEPLOY_URL → stored deploy_url → http://localhost:8090.
• Token: --token → CHIDORI_API_KEY → stored deploy_api_key (missing is a hard error).

--url / --token work on any deploy subcommand.

Approval postures

The posture decides what happens when an agent reaches a gated effect. Exactly four target families are gated: network (fetch / node:http), chidori.tool calls, workspace access (writes and deletes ask; list, read, and manifest route through the same gate but are allowlisted in both built-in profiles), and app-data. LLM prompts and pure compute are never gated.

Explicit policy configuration takes precedence in the order CHIDORI_POLICY_FILE → CHIDORI_POLICY → CHIDORI_POLICY_PROFILE → the command's default. The full model — profiles, policy files, per-session overlays — is in the Sandbox Model.

Exit codes

Every command exits 0 on success and 1 on failure, with two exceptions:

• chidori check exits 2 on validation failure.
• chidori resume --ci exits 0 on a clean match, 3 on divergence, and 1 on error, always with a JSON report.

chidori verify is plain 0/1 — no separate divergence code — but each failure mode gets a distinct message.