cli.md

CLI reference

All commands accept --root <path>. If omitted, arc uses the current directory.

init

arc init

Creates .agent/contracts, .agent/archive, and starter templates under .agent/templates.

new

arc new goal auth-refresh --title "Fix auth refresh"
arc new loop nightly-check
arc new eval-loop ranking-eval
arc new monitor-loop production-watch

Creates a v2 run directory.

Use --force to overwrite an existing run directory.

lint

arc lint auth-refresh
arc lint .agent/contracts/auth-refresh
arc lint .agent/contracts/auth-refresh/arc.toml --strict

Checks TOML syntax, required fields, path policy, command policy, proof definitions, pause rules, and vague language in the prompt.

--strict turns warnings into failures.

launch

arc launch --agent codex auth-refresh --print
arc launch --agent claude auth-refresh --print

Activates the run, records the current contract hash, writes prompt and hook artifacts under launch/, and prints the command to run.

arc launch never starts the agent itself.

hook

arc hook claude pre-tool auth-refresh
arc hook claude post-tool auth-refresh
arc hook claude stop auth-refresh

arc hook codex pre-tool auth-refresh
arc hook codex permission-request auth-refresh
arc hook codex post-tool auth-refresh
arc hook codex stop auth-refresh

Hooks read host hook JSON from stdin and print the host-specific decision JSON.

Use auto when exactly one run is active:

arc hook codex stop auto

validate

arc validate auth-refresh

Reruns verifiers and updates proof state. This is the only path to Verified or Rejected.

status

arc status auth-refresh
arc status auth-refresh --json

Prints run status, proof state, forbidden changes, and changed files.

doctor

arc doctor --agent all auth-refresh
arc doctor --agent claude auth-refresh
arc doctor --agent codex auth-refresh

Checks the local supervisor setup: git root, arc wrapper, plugin manifests, hook JSON, skill files, active contract hash, contract lint, evidence directory, and adapter policy simulations.

Codex hook trust cannot be proven from arc, so doctor reports it as an ACTION and tells you to review /hooks in Codex.

report

arc report auth-refresh

Writes and prints .agent/contracts/auth-refresh/final.md.

amend

arc amend auth-refresh add-readme.toml

Applies a proposal from proposals/, saves the previous contract as arc.vN.toml, increments contract_version, and refreshes the state lock.

tui

arc tui
arc tui --snapshot

Shows active runs, proof counts, drift state, recent events, and git diff summary.

archive

arc archive auth-refresh

Marks the run archived and moves it to .agent/archive/<id>.