CLI Reference

This is the command reference for the anode binary. It lists the command surface and the command families that consume each run-scoped flag.

Root Command

anode

Open the interactive TUI.

anode -x "prompt"

Run one prompt without opening the TUI.

Global Flags

Cobra exposes these persistent flags on many subcommands. Runtime support is command-specific, and unsupported flag/command combinations are rejected before the command runs.

Flag	Use
`-x`, `--execute`	Run a prompt from the root command.
`--profile <name>`	Profile for `execute`, `runs start`, `tools`, and `review`.
`--model provider/model`	Model override for `execute`, `review`, and `runs start`.
`--max-turns <n>`	Turn limit for `execute`, `review`, and `runs start`.
`—approval ask	auto
`--run-label <label>`	Label for `execute` and `runs start`; whitespace-only daemon run labels are rejected.
`--allow-tool <name>`	Repeat or comma-separate tool allowlist for `execute`.
`--stream-json`	JSON events for `execute`, `review`, and `attach`.
`--stream-json-input`	JSON stdin for `execute`; requires `--stream-json`.
`--archive`	Archive the session thread after an `execute` run completes.
`--stats`	Print token usage and cost summary after `execute` runs.

Unsupported run-scoped flags are rejected instead of being silently ignored. For example, --allow-tool, --archive, --stats, and --stream-json-input are execute-only.

`execute`

Alias: exec.

anode execute "summarize this repository"
anode exec "summarize this repository"
anode -x "summarize this repository"

If no prompt argument is supplied, Anode reads stdin:

cat failure.log | anode execute

Common flags:

anode -x \
  --profile study \
  --model anthropic/claude-sonnet-4-6 \
  --max-turns 20 \
  --approval auto \
  --allow-tool read \
  --allow-tool finder \
  "debug this failure"

`review`

anode review
anode review "focus on auth and data exposure"
anode review --base main
anode review --base main --checks
anode review --base main --stream-json

Flags:

Flag	Use
`--base <ref>`	Diff against a base ref.
`--checks`	Run `.agents/checks/*.md` project checks.
`--profile <name>`	Review profile override. Defaults to review behavior.
`--model provider/model`	Model override for review runs.
`--max-turns <n>`	Turn limit for each review run.
`—approval ask	auto
`--stream-json`	Emit JSON events.

`login`

Authenticate with OpenAI.

anode login
anode login --device-auth

--device-auth is useful on remote or headless machines.

`doctor`

anode doctor

Checks local Anode health without making a model request. It reports the workspace, harness artifact root, config discovery status, provider configuration, MCP/LSP config diagnostics, effective tool contract status, and local harness artifact health. The tools section includes smoke-mode counts for the effective runtime tool contracts. The harness section includes run/report failure counts, bounded failed samples, and malformed ledger diagnostics. It labels that rollup as all-history and also prints current-head evidence, which shows whether this git commit has fresh harness evidence or needs a diagnostic run before it is trusted. It uses the shared harness status reader, so stale running ledgers older than the recovery cutoff may be marked failed before they are reported; it does not replay prior runs or make model requests. It exits nonzero when config loading, extension config diagnostics, or tool contracts fail.

`harness`

anode harness list
anode harness list --limit 5
anode harness context
anode harness context --limit 3
anode harness check
anode harness check --gate contracts
anode harness check --gate config-auth
anode harness check --gate provider
anode harness check --gate provider-live
anode harness check --gate mcp
anode harness check --gate lsp
anode harness check --gate tui
anode harness check --gate fast
anode harness check --gate full
anode harness check --gate vet
anode harness check --gate build
anode harness check --gate tool-smoke
anode harness check --gate bench
anode harness check --gate bench-validation
anode harness check --gate bench-heldout
anode harness check --gate local
anode harness check --gate all
anode harness status
anode harness status --limit 10
anode harness status --scope latest
anode harness status --scope current-head
anode harness smoke
anode harness bench --dry-run
anode harness bench --suite heldout
anode harness bench --case permission-denial
anode harness bench --agent
anode harness bench --agent --agent-profile study --agent-model provider/model --agent-max-turns 8
anode harness bench --jobs 4
anode harness inspect <run-id>
anode harness inspect <run-id> --limit 0
anode harness ledger <run-id>
anode harness replay <run-id>
anode harness replay <run-id> --limit 20
anode harness replay <run-id> --execute-read-only --allow-external-read --allow-workspace-drift --allow-runtime-drift

harness check writes a check report under .anode-harness/checks/ and exits nonzero for failed gates. --gate can be repeated or comma-separated. The config-auth gate includes main config, auth loading, MCP config diagnostics, and LSP config diagnostics. The optional mcp gate connects configured MCP servers and records per-server status/tool/resource counts in mcp.json; the optional lsp gate records configured language-server command availability in lsp.json without launching the servers. The provider-live gate is opt-in because it spends a live provider request. The bench gate runs the benchmark fixture dry-run and links the benchmark report from bench.json using both an absolute benchmark_report_path and a portable benchmark_report_artifact relative to .anode-harness/. Use bench-validation or bench-heldout when the validation and held-out fixture splits should be checked and logged separately. JSON mode prints the report but still exits nonzero when check, smoke, or bench records ok: false.

harness list returns recent run ledgers; --limit 0 means all runs and negative limits are rejected by both the CLI and harness summary reader.

harness status scans all local run ledgers plus check, smoke, benchmark, and replay reports for pass/fail counts, then applies --limit only to displayed rows. It exits nonzero if any scanned run/report failed or if artifact diagnostics were found. Use --json for the structured rollup. Use --scope latest for a current-health rollup that evaluates the newest run and newest diagnostic artifact per kind while printing the excluded historical counts. --scope current-head evaluates only evidence captured at the current git HEAD, including replay reports attached to runs from that HEAD; it fails with a scope diagnostic when no evidence exists for the current commit or when the live workspace has uncommitted non-harness changes not covered by committed evidence. Use the default scope when auditing preserved failures. Check, smoke, benchmark, and replay text output includes compact environment evidence where available; the JSON reports include the full runtime/git snapshot, and harness status surfaces the saved git provenance on diagnostic report summaries. Benchmark rows also include validation vs held-out suite scores when the report records them.

harness context prints the same compact harness context used by the TUI and agent prompt builder. It includes ledger paths, failure snippets, validation failure snippets, run durations, artifact counts, and recent check/smoke/bench/replay report summaries with artifact paths and benchmark outcome counts. It accepts --json for automation. harness list and harness context also surface malformed ledger diagnostics.

harness smoke runs deterministic local tool smoke paths where possible, validate-only paths for interactive, delegated, web, and provider-backed tools, uses the configured runtime tool surface, and writes .anode-harness/smoke/<run>/report.json. Executed smoke rows include changed_files; change_scan_error fails the smoke report if Anode cannot prove fixture changes.

harness bench --dry-run validates the benchmark fixture definitions without running their commands. harness bench runs the local fixture validation commands in fixture runner mode. harness bench --agent runs each case through headless Anode in the detached worktree before validation and records the child run ledger on the case row. The agent runner is pre-constrained to a small benchmark tool set, checks file edit/create/patch targets against allowed_write_scopes before execution, and rejects shell commands that appear to write. Restricted agent runs also reject state-writing and interactive tools because those effects cannot be represented by file write scopes. Use --agent-profile, --agent-model, and --agent-max-turns to pin agent routing for repeatable benchmark runs, and --jobs <n> to run independent cases with bounded concurrency. Benchmark reports record aggregate scores, per-suite validation/held-out scores, case-scoped failures, outcomes, runner mode, run config, parallelism, timings, changed files, and scope violations under .anode-harness/bench/. Use --suite validation or --suite heldout to run one split at a time; use --case <id> for a focused fixture or repeat it for a small case set. Suite and case filters are saved in the report. Non-dry benchmark runs require a git workspace so write-scope enforcement cannot be silently disabled. Cases run in temporary detached worktrees from current HEAD, so commit the candidate state before benchmarking it. A dirty live workspace fails the top-level report and lists the changed files. Text output shows the aggregate score, pass/fail/planned counts, runner mode, fixture root, fixture files, git HEAD, history path, history quarantine path when a corrupt history file was moved aside, aggregate token/cost usage when available, and trend when available, plus per-suite counts and per-case suite, runner, artifact, change, scope-violation, responsible receipt, missing-required-change, and diff paths. Cases with required_changed_files print missing_required=... when validation passed without required file changes. Runner-backed scope violations preserve the child run ledger in the benchmark artifact directory when available, so responsible_path= can be inspected after the detached worktree is removed. Trend output includes token and cost deltas when both benchmark runs recorded usage. Trend baselines are selected only when the saved run config is compatible; otherwise the trend is no-compatible-baseline.

harness inspect, ledger, and replay read filesystem-backed run artifacts from .anode-harness/runs/. harness inspect --limit 0 prints every detail record instead of the default recent subset. Text inspect and replay include run timing and token/cost usage when recorded plus compact validation stdout, stderr, error, timeout, class, working directory, provider retry rows, and recovery evidence when present. Inspect also prints the run artifacts[] ledger so receipt and diff files are discoverable from text output. harness list prints each run’s artifact-relative ledger path when available. replay is non-executing: it classifies recorded steps as safe read-only candidates, inspect-only writes/executes, blocked calls, failed calls, or unknown records. Replay output includes provider retry rows so hidden rate-limit or server-error backoff is visible during audits. replay --limit <n> prints only the last n records in each section while preserving the original tool-call numbering; --limit 0 prints the full replay plan. Add --execute-read-only to rerun only successful local read-only candidates that have raw call arguments recorded; external-read candidates stay skipped unless --allow-external-read is supplied, and every other receipt is still printed as skipped or inspect-only. Execution is blocked when the current workspace is dirty or at a different git HEAD than the recorded run unless --allow-workspace-drift is supplied. Execution is also blocked when the recorded profile/model, permission summary, tool registry surface, or per-tool permission class differs from the current runtime unless --allow-runtime-drift is supplied. Executed read-only replays write a timed replay artifact under the original run, update the artifact ledger, and print the saved report path. If replayed stdout, stderr, error, or exit status no longer matches the original receipt summary, replay exits non-zero and records the mismatch fields plus a capped diff in the report.

Pass --json to harness list, check, smoke, or bench when automation needs structured output. See Harness, doctor, and ledgers.

`config`

anode config
anode config path
anode config list
anode config ls
anode config doctor

config is the same as config list. config path prints one absolute effective config path and exits nonzero when no config file is effective. If $ANODE_CONFIG is set but cannot be loaded, stdout still prints the fallback path and stderr carries the warning. config list shows config discovery order and per-candidate status; config ls is an alias. config doctor validates discovery, parsing, duplicate keys, and safety checks for CI or release gates; successful checks end with Config doctor passed.. See Configuration for the loading precedence model.

`lsp`

anode lsp
anode lsp list
anode lsp ls
anode lsp doctor

lsp is the same as lsp list. lsp list shows configured and auto-detected language servers. lsp doctor validates language-server config discovery and parsing; successful checks end with LSP diagnostics passed.. See Language Server Protocol for config file locations and server setup.

`tools`

anode tools
anode tools list
anode tools ls
anode tools list --profile review
anode tools show read
anode tools read
anode tools use read --arg path=README.md
anode tools use chart --arg type=bar --arg-json data='{"fixed":3,"open":1}'

tools is the same as tools list. tools <name> is the same as tools show <name>; tools ls is an alias. tools list shows built-in, MCP, toolbox, and process-plugin tools that are currently registered. tools show <name> prints the tool type and permission level. tools use invokes read-only tools (auto_read and external_read) directly. Pass raw string arguments with --arg key=value, structured values with --arg-json key=<json-value>, or a full object with --json. Pass --allow-non-read only when you intentionally want to run tools that write state, write files, execute commands, delegate, or ask interactively.

`skills`

anode skills
anode skills list
anode skills ls
anode skills info code_review
anode skills code_review
anode skills show code_review
anode skills add ./release-skill --name release
anode skills add ./release-skill/SKILL.md --name release --target .agents/skills
anode skills remove release
anode skills rm release

skills is the same as skills list. skills <name> is the same as skills info <name>. skills add installs from a local SKILL.md file or skill directory. The default target is ~/.config/anode/skills; use --overwrite to replace an existing installed skill.

`permissions`

anode permissions
anode permissions test bash --command "go test ./..."
anode permissions bash --command "go test ./..."
anode permissions list
anode permissions ls
anode permissions add reject bash --match 'command=rm -rf *'
anode permissions add ask edit_file --match 'path=*.lock' --workspace

permissions is the same as permissions list; permissions ls is an alias. permissions <tool> is the same as permissions test <tool> and accepts the same test flags. permissions add prepends a rule to the global config by default. Test-only flags such as --command, --path, --query, and --arg require a tool name. Pass --workspace to update .agents/permissions.json.

`permissions test`

Preview a permission decision without running the tool.

anode permissions test bash --command "go test ./..."
anode permissions test read --path README.md
anode permissions test finder --query "func main"
anode permissions test bash --context child_run --arg command="git status"
anode permissions test bash --preset careful --command "rm -rf tmp"

Flags:

Flag	Default	Use
`--context`	`main_run`	`main_run` or `child_run`.
`--preset`	-	Include a preset for this inspection: `unrestricted`, `careful`, or `strict`; `yolo` is an alias for `unrestricted`.
`--command`	-	Set `command` argument.
`--path`	-	Set `path` argument.
`--query`	-	Set `query` argument.
`--arg key=value`	-	Add any other argument. Repeatable.

`mcp`

anode mcp
anode mcp list
anode mcp ls
anode mcp list --connect
anode mcp doctor
anode mcp status
anode mcp info
anode mcp info docs
anode mcp tools
anode mcp resources
anode mcp read docs docs://intro
anode mcp reload
anode mcp add docs --url https://example.com/mcp
anode mcp add local --env TOKEN=... -- npx -y @modelcontextprotocol/server-filesystem .
anode mcp remove docs
anode mcp trust
anode mcp approve
anode mcp trust /path/to/project

mcp is the same as mcp list. mcp <server-name> is the same as mcp info <server-name>; mcp ls is an alias.

mcp doctor validates MCP config and tests configured server connections; successful checks end with MCP doctor passed..

--timeout applies only to connected MCP operations:

anode mcp list --connect --timeout 20s

Use it with mcp <server-name>, mcp doctor, mcp resources, mcp read, mcp status, mcp info, mcp tools, mcp reload, or mcp list --connect. Explicit timeout values must be greater than zero.

OAuth commands for remote MCP servers:

anode mcp oauth status
anode mcp oauth login <server-name> --client-id <client-id>
anode mcp oauth login <server-name> --server-url https://mcp.example.com --client-id <client-id> --scopes "read write"
anode mcp oauth logout <server-name>

oauth login requires --client-id. --server-url is optional only when the server URL exists in user MCP config or in a trusted workspace MCP config.

`hooks`

anode hooks
anode hooks list
anode hooks ls
anode hooks doctor

hooks is the same as hooks list; hooks ls is an alias. It inspects shell hooks and process plugin hook configuration. hooks doctor validates that configuration; successful checks end with Hook diagnostics passed..

`plugins`

Alias: plugin.

anode plugins
anode plugins list
anode plugins ls
anode plugins reload
anode plugins activity
anode plugins doc
anode plugins exec /path/to/plugin

plugins is the same as plugins list; plugins ls is an alias. plugins doc prints the process plugin protocol. plugins exec discovers one plugin executable from a path and lists its contributed tools without requiring the plugin to be in config. plugins activity explains that process plugin activity is not persisted and points to anode plugins list for configured plugin paths and contributed tools.

`debug bundle`

anode debug bundle
anode debug bundle --output /tmp/anode-debug.zip
anode debug bundle --thread <thread-id>

Creates a support bundle containing config, selected environment details, and optionally a thread. Use it when reporting a reproducible Anode issue.

`daemon`

anode daemon
anode daemon --addr 127.0.0.1:7433
anode daemon --addr /tmp/anode.sock

With no --addr, Anode listens on:

~/.config/anode/daemon.sock

`runs`

Manage daemon runs.

anode runs
anode runs --limit 10
anode runs list
anode runs list --limit 10
anode runs start "investigate flaky tests"
anode runs start --profile study --model openai/gpt-5.5 --max-turns 10 --approval auto --run-label ci "summarize failures"
anode runs cancel <run-id>

Use a non-default daemon address:

anode runs --daemon 127.0.0.1:7433
anode runs --addr 127.0.0.1:7433

runs is the same as runs list. Use --limit <n> to return at most n runs; 0 means all runs. --addr is an alias for --daemon.

`attach`

Attach to a daemon run.

anode attach <run-id>
anode attach --stream-json <run-id>
anode attach <run-id> --daemon 127.0.0.1:7433
anode attach <run-id> --addr 127.0.0.1:7433

attach accepts the same --daemon and --addr daemon address flags as runs.

`threads`

anode threads
anode threads list
anode threads ls
anode threads search "release notes"
anode threads "release notes"
anode threads read <thread-id>
anode threads markdown <thread-id>
anode threads export <thread-id>
anode threads usage <thread-id>

threads is the same as threads list. threads <query> is the same as threads search <query>; threads ls is an alias.

Use --limit <n> to return at most n recent or matching threads. Thread list/search limits and read/markdown --max-items values must be greater than zero. threads export --max-items 0 exports all messages/events.

`update`

anode update
anode update --force
anode update --version v1.2.3

Flag	Use
`--force`	Re-download even if already on latest.
`--version <version>`	Install a specific version instead of latest.

Downloads the binary for your platform, verifies the SHA-256 checksum, and atomically replaces the running binary.

`uninstall`

anode uninstall --dry-run
anode uninstall
anode uninstall --force

Without --dry-run or --force, Anode asks you to type uninstall.

`completion`

anode completion bash
anode completion zsh
anode completion fish
anode completion powershell

Prints shell completion scripts generated by Cobra.

Exit Behavior

For headless commands, exit code 0 means success. Non-zero means Anode could not complete the command, the run failed, validation failed, a provider was not available, or a required prompt/config value was missing.

Keep going: