CLI reference
Audience: coding agents and integration operators. CLI commands and schemas below are system reference, not a user checklist. Users can follow Quickstart.
In plain words: this page lists every claude-foundation command, grouped by whether it only reads, changes a change in progress, or needs your explicit authority. It is for agents, integrators, and anyone who wants to read what the agent is doing. You need Change Loop installed; you get the exact command, its purpose, and the protocol versions it speaks. Unfamiliar words (change, claim, receipt, provider, capability) are in the glossary.
Your agent runs these; you rarely need to. They are documented so you can read what the agent is doing, and drive it yourself when you want to.
Every command answers --help, and claude-foundation describe [command] [--json] describes the surface — including the optional /deliver command, /changes, and the /feature compatibility alias, resolvable by bare word or /slash spelling, read from the shipped command files so there is no second copy to drift.
Primary agent surface
Section titled “Primary agent surface”Normal users issue /investigate, /change, /build, /prove, /land,
optional /deliver, or /dev; the agent owns CLI details. Its compact runtime
surface is:
| Command | Purpose |
|---|---|
investigate --template | <record.json> |
Validate source-bound facts and hypotheses, persist resume state, and emit a Change handoff |
change start --template | <draft.json> [--inspect] [--consume-draft] [--approve-spec --decision-ref <ref> [--through <target>]] |
Inspect a draft and, when complete, compile and atomically start it in one call; --inspect inspects only; --approve-spec records the user’s approval in the same call |
change amend --template | <change> <amendment.json> [--inspect] [--consume-amendment] [--approve-spec --decision-ref <ref> [--through <target>]] |
Inspect intake and, when complete, transactionally add, revise, or remove requirements, or fix an unfinished task’s verify command, during Build in one call |
change amend <change> --task <task> --verify <command> [--reopen] [--reason <text>] |
Correct a task’s wrong verify command directly, keeping the approval (--reopen for a completed task); the task is accepted only when the new command passes |
advance <change> --through build|proven|archived |
Run deterministic lifecycle work (evidence wiring, sandbox sync, agent-runnable review, task ticking) and return one of seven bounded actions (WORKING while harness work runs) at the next real boundary |
advance <change> --approve-spec [--role <role>] --decision-ref <ref> |
Record the user’s spec approval (alias of change resolve --approve-spec); with approval.roles configured, --role approves one lane and omitting it covers every lane |
exec <change> [--repo <id>] [--task <id>] -- <command…> |
Run and time a command (a task’s checkCommand, a build, a full test run) in the change’s sandbox: the named repository or task, else the caller’s directory, else the pending tasks’ repository; never the main checkout |
deliver advance <change> |
After explicit /deliver, automate isolated commit, feature-branch push, PR creation/reuse, provider verification, and return the URL |
changes |
Read active state and the next useful route |
doctor … |
Diagnose a route only when the coordinator asks for it |
claude-foundation help shows this small surface. help --all exposes the
compatible primitives below for operators and host integrations.
Read-only
Section titled “Read-only”Safe to run at any time. These mutate nothing, except that package writes
its own read-only HTML file.
| Command | Purpose |
|---|---|
changes |
List active changes, lifecycle status, and each one’s next useful action |
current |
Print the single active change with its status and next command; with none or several, list the candidates and exit non-zero. While exactly one change is active, advance, packet, metrics, feedback, and package may omit <change>; Land and approval flags always need the explicit id |
doctor [--stage change|build|prove] [--change <id>] |
Diagnose project, provider, and lifecycle readiness |
packet <change> [--phase <phase>] [--repo <id>] [--task <id>] |
Read the bounded machine handoff for the current operation |
metrics <change> |
Inspect measured usage, semantic-intake effectiveness, active budget, cost, and execution timing |
package <change> [--pretty] |
Write the read-only approval package .foundation/packages/<change>.html (risk level, technical domains, artifacts by approver role with proof/preview/no-evidence labels, embedded Mermaid diagrams, suggested previews for High/Critical); idempotent, writes only that file, never changes lifecycle state |
budget checkpoint <change> |
Show measured remaining allowance, unfinished work, and the exact resume route |
feedback <change> |
Explain reviewer, evidenced repair, human-wait, and unattributed timing; show reuse and the next action |
change audit <change> |
Audit scenario, claim, task, and provider traceability |
proof readiness <change> |
Typed blockers and canonical next commands |
land check <change> |
Run the checks Land runs before it writes, read-only, and report current assurance; refuses unproven work like Land |
handoff status <change> |
Inspect permission-bound operations and their Land disposition |
handoff list [--open] [--owner <team>] [--environment <env>] [--json] |
List operational obligations across active and archived changes |
handoff packet <change> [--id <H00n>] |
Read the credential-free packet for a named DevOps/SRE owner |
repos [change] |
Inspect repository topology and selection |
models |
Inspect model-tier policy |
providers |
Inspect evidence wiring while defining a change contract |
version |
Print the installed package version |
Consumer quality
Section titled “Consumer quality”See Consumer quality gates for configuration, language profiles, baselines, and rollout policy.
| Command | Purpose |
|---|---|
quality discover [--change <id>] |
Read repository manifests and report detected languages, profiles, providers, and unsupported capabilities without executing project commands |
quality init [--change <id>] [--write] [--force] [--ci github] |
Preview consumer quality config; explicitly write it and optional GitHub workflow templates |
quality doctor [--change <id>] [--enforce] |
Validate selected repositories, provider configuration, executable availability, and mutation isolation |
quality run [--change <id>] [--repo <id>] [--capability <name>] [--full] [--shard-index <n> --shard-count <n>] [--enforce] |
Run per-repository lanes and apply changed-code or full-inventory ratchets |
quality report |
Read the latest non-averaged repository-lane summary |
quality baseline [--repo <id>] [--capability <name>] [--write --decision-ref <ref> --reason <why>] |
Preview or explicitly approve versioned CRAP/mutation baselines |
quality debt |
Render JSON and Markdown debt from the latest run without widening Change scope |
The change lifecycle
Section titled “The change lifecycle”| Command | Purpose |
|---|---|
investigate --template | <record.json> |
Print or validate a versioned investigation record and return one typed action |
change new <intent> [--rapid] |
Compatible primitive for manually authoring a change agreement |
change start --template | <draft.json> [--inspect] [--consume-draft] [--approve-spec --decision-ref <ref> [--through <target>]] |
Inspect and, when complete, compile and start an agreement from one semantic draft (a JSON file or a draft v5 folder) in one call; Build creates isolation later; --approve-spec records the user’s approval in the same call |
change amend --template | <change> <amendment.json> [--inspect] [--consume-amendment] [--approve-spec --decision-ref <ref> [--through <target>]] |
Inspect intake and, when complete, add, revise, or remove semantic requirements, or fix an unfinished task’s verify command, transactionally while preserving completed work, in one call |
change amend <change> --task <task> --verify <command> [--reopen] [--reason <text>] |
Correct one unfinished task’s verify command without amendment JSON; claims, capabilities, and approval stay, an always-passing command is refused, and --reopen unticks a completed task so it must pass again |
change revise <change> <draft.json> [--merge] [--inspect] [--consume-draft] [--approve-spec --decision-ref <ref> [--through <target>]] |
Before Build, inspect and, when complete, recompile a revised semantic draft over the same change id in one call, with rollback and a requirement delta (approval carries unless a requirement is removed); --merge takes only the changed keys and keyed entries |
change resolve <change> … |
Persist impact, coupling, security, and review decisions |
change validate <change> |
Validate the change and its executable evidence contract |
preview <change> --provider <name> [--decision-ref <ref>] [--pretty] |
Optional, before Build only: copy the target into .foundation/previews/<change>/workspace (no Git, no harness state), run one declared provider there, and record a kind: "preview" receipt; preview receipts never satisfy Prove or Land and never block approval or Build; an external: true provider needs the user’s --decision-ref or is refused with PREVIEW_AUTHORITY_REQUIRED |
sandbox create <change> [--all] |
Create the isolated Build workspace |
sandbox sync <change> |
Synchronize an intentional contract revision into Build |
advance <change> [--through build|proven|archived] [--host-result <result.json>] |
Normal model-facing coordinator; run safe deterministic steps and return one bounded action |
proof advance <change> |
Compatible Prove primitive used internally and by explicit integrations |
proof collect <change> |
Low-level collection for diagnosis or an explicit integration |
proof run <change> |
Low-level atomic run when no resumable external handoff is needed |
handoff record <change> --id <H00n> … |
Record accepted/completed/rejected/cancelled/superseded operational outcomes and durable references |
Evidence wiring
Section titled “Evidence wiring”| Command | Purpose |
|---|---|
evidence detect <change> |
Detect safe project-owned provider candidates without executing them |
evidence init <change> [--write] |
Preview, or explicitly write, high-confidence provider wiring |
evidence doctor <change> |
Explain configured, detectable, and unresolved wiring |
evidence verify-ci <change> <provider> <signed.json> |
Verify signed CI provenance bound to the provider workspace |
External authority
Section titled “External authority”Review and acceptance, resumable across sessions. Prefer advance; use
these directly for diagnosis or an explicit integration.
| Command | Purpose |
|---|---|
authority request <change> --type review|acceptance |
Create a resumable external request |
authority status <change> [--request <id>] [--template] |
Inspect authority; --template emits the response file to fill in |
authority dispatch <change> … |
Reserve the exact full/delta packet when handing review to an AI or named human |
authority run <change> … |
Run the configured read-only ephemeral AI reviewer and record its real session |
authority abort <change> … |
Close an unusable request without pretending its dispatched attempt completed |
authority record <change> --request <id> --response <file> |
Validate a bound host response and record its evidence |
evidence record <change> <provider> <status> … |
Low-level integration path for externally observed evidence |
Landing
Section titled “Landing”| Command | Purpose |
|---|---|
land archive <change> |
Low-level apply, synchronize, audit, archive, and cleanup primitive; normal agents use advance --through archived |
land record <change> --repo <id> --commit <sha> --decision-ref <ref> |
Legacy compatibility for an active commit-oriented transaction |
land resume <change> |
Diagnostic resume primitive; normal recovery repeats /land |
Optional pull-request delivery
Section titled “Optional pull-request delivery”| Command | Purpose |
|---|---|
deliver advance <change> |
One composition command for an archived change; the harness owns readiness, isolated worktree, projection guard, PR-standard rendering, commit, push, provider read-back, retry, and resume |
If /deliver is absent, no delivery directory, PR-specific evidence work, or
gate is created. On a proven change that is not archived yet, /deliver is
also Land authority: the harness lands it through advance --through archived
and continues delivery. The explicit command never authorizes force-push,
default-branch push, merge, deploy, publish, or product edits. Success requires
an open PR whose provider-reported base, head, and commit match the durable
delivery receipt.
Recovery and escape hatches
Section titled “Recovery and escape hatches”| Command | Purpose |
|---|---|
sandbox create <change> --all |
Repair missing multi-repository bindings in place; valid existing worktrees are preserved |
advance <change> --decision <option> --decision-fingerprint <hash> --decision-ref <ref> --reason <approach> |
Record the user’s answer to an advance decision (retry, wait, pause, merge, or retain, as offered) and resume its target |
advance <change> --through archived --restore-target <paths> [--decision-ref <ref>] |
Restore conflicting target paths to the sandbox base inside Land; anything other than regenerable artifacts needs the user’s decision |
advance <change> --through archived --recover-apply settle|keep-current|restore-backup --decision-ref <ref> |
Settle an interrupted Land apply under the user’s decision, then continue |
advance <change> --undo-land --decision-ref <ref> |
Undo an archived Land whose diff is still uncommitted; refuses without writing if HEAD moved or a landed path was staged or edited |
change abandon <change> --reason <r> --decision-ref <ref> |
Quarantine a change that cannot be proven |
change waive <change> --capability <c> --reason <r> --decision-ref <ref> |
Withdraw one capability’s enforcement after its provider ran and failed; --revoke restores it |
budget continue <change> --reason <r> --decision-ref <ref> |
Optional explicit widening; exhausted windows auto-continue |
agents release <change> <task> --owner <id> [--lease-id <id>] [--force] |
Release a lease; a taken-over generation requires its acquired lease id, and --force takes over one whose owner crashed |
Commands marked as needing a --decision-ref require an explicit host-recorded user decision. The runtime will not accept the agent’s own judgement in their place.
Administration
Section titled “Administration”| Command | Purpose |
|---|---|
init [target-path] [--host claude|cursor|opencode|codex] [--yes] |
Install or upgrade Change Loop in a project; --host adds that host’s adapter |
help [--all] |
Canonical commands; --all includes compatibility routes |
dashboard [-up|-status|-down] |
Manage the optional team-presence client |
migrate [legacy-id] [--apply] |
Migrate corroborated legacy workflow records |
Protocol versions
Section titled “Protocol versions”advance <change> --inspect reads the next action without executing work; it
cannot be combined with --through or --host-result.
packet <change> --resume returns bounded current agreement references,
frontier, leases and evidence. Read referenced sections when marked truncated.
feedback <change> --diagnostics exports allowlisted local metadata with
provider aliases; paths, commands and free-form payloads are excluded.
Build/Prove completion is TARGET_REACHED; archived delivery is DELIVERED.
Feedback reports current runtime receipt validity. Dashboard recorded proof
remains unverified when current workspace freshness cannot be checked.
Wire-visible contracts are pinned in .claude/harness/protocol.json. A mixed-revision install fails immediately at load rather than partway through Land.
| Pin | v3.6.7 |
|---|---|
| runtime | 3.6.7 |
| runtime API | 42 |
| semantic draft schema | 5 |
| semantic intake state schema | 2 |
| semantic amendment schema | 1 |
| artifact defaults schema | 2 |
| grounding schema | 1, 2, 3 |
| advance protocol | 6 |
| provider protocol | 13 |
| evidence schema | 1, 2 |
| packet schema | 12 |
| proof protocol | 7 |
| review protocol | 4 |
| acceptance protocol | 2 |
| semantic acceptance protocol | 1 |
| attestation protocol | 1 |
| authority protocol | 2 |
| quality capabilities protocol | 1 |
| CRAP protocol | 1 |
| automated mutation protocol | 1 |