Headless Execution

Use headless mode when you want Anode to do one job and exit. It is the right surface for shell scripts, CI, and programmatic callers.

One Prompt

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

If no prompt argument is given, Anode reads stdin:

cat prompt.txt | anode execute

When you want to combine an instruction with piped content, include both in stdin or build one prompt string:

{ printf 'diagnose this failure:\n\n'; cat failure.log; } | anode execute

Useful Flags

anode -x \
  --profile study \
  --model anthropic/claude-sonnet-4-6 \
  --max-turns 20 \
  --approval auto \
  --run-label local-debug \
  "debug this test failure"

Flag	Use
--profile	Select a built-in or custom profile.
--model	Override the model for this run.
--max-turns	Stop after a fixed number of model/tool turns.
--approval	ask, auto, or unrestricted; yolo is an alias for unrestricted.
--run-label	Attach a label to the run.
--allow-tool	Restrict tool access. Repeat or comma-separate values.
--stream-json	Emit newline-delimited run events.
--stream-json-input	Read JSON user messages from stdin. Requires --stream-json.

Limit Tools

anode -x \
  --allow-tool read \
  --allow-tool finder \
  --allow-tool web_search \
  "find public API handlers"

When --allow-tool is present, the run receives only those tool names or glob patterns.

Approval Modes

Mode	Use
ask	Default. Ask before risky tools. Can block non-interactive runs.
auto	Let policy auto-approve allowed calls. Good for read and safe shell workflows.
unrestricted	Skip confirmation. Use only in disposable workspaces.

For automation, prefer explicit permissions and tool allowlists over unrestricted.

Stream JSON Output

anode -x "summarize this repository" --stream-json

Each stdout line is a JSON object:

{
  "id": "evt_123",
  "run_id": "R_123",
  "type": "system.init",
  "status": "running",
  "payload": {
    "profile_name": "craft",
    "active_model": "anthropic/claude-sonnet-4-6",
    "web_enabled": true,
    "tools": ["read", "finder"],
    "permission": {
      "context": "main_run",
      "rules": 3,
      "allow": 1,
      "reject": 1,
      "ask": 1
    }
  },
  "created_at": "2026-05-12T00:00:00Z"
}

Fields:

Field	Use
id	Event ID.
run_id	Run ID.
parent_run_id	Parent run ID for child runs. Omitted when empty.
parent_tool_use_id	Tool call that spawned a child run. Omitted when empty.
type	Event type.
status	running, waiting_approval, complete, error, or canceled.
payload	Type-specific JSON data.
created_at	Timestamp.

Event types currently include:

Type	Meaning
run.started	Run created.
system.init	Model, profile, tools, web, MCP status, and compact permission policy counts.
user.message	User prompt.
assistant.message	Assistant text.
tool.call	Tool call prepared.
tool.result	Tool result returned.
approval.requested	Tool approval needed.
approval.resolved	Approval completed.
validation.started	Validation started.
validation.result	Validation result, including status, class, stdout/stderr evidence, recovery hint on failure, or skip_reason when validation was skipped.
child_run.started	Subagent started.
child_run.result	Subagent finished.
usage	Token usage update when the provider reports it.
result.final	Final run result.
error	Run error.
canceled	Run canceled.

Example:

anode -x "run tests" --stream-json | jq -c 'select(.type=="result.final")'

Stream JSON Input

anode -x --stream-json --stream-json-input

Send one JSON object per line:

{"type":"user","message":{"role":"user","content":"find the CLI entrypoint"}}

The message schema:

Field	Use
type	Must be user.
steer	Optional boolean. true injects guidance at the next safe interruption point.
message.role	Must be user.
message.content	String or content block array.

Content block example:

{"type":"user","message":{"role":"user","content":[{"type":"text","text":"now inspect the config loader"}]}}

Anode exits after stdin closes and the active turn finishes.

Exit Codes

0 means the command completed successfully. Non-zero means setup failed, provider/model selection failed, the run failed, validation failed, or a required prompt/config value was missing. If the event stream closes without a final result, Anode records an immediate harness error event for the run when the run ID is known, so the ledger does not wait for stale-run recovery to become inspectable.

Provider startup failures are explicit. Direct headless errors keep the not connected prefix and include the typed active provider/model detail plus a recovery hint. Stream JSON runs carry the same provider detail in the result.final payload and run ledger instead of collapsing missing active config, malformed active model strings, missing providers, and removed models into an indistinct runtime error.

Keep going:

• Automation
• CLI reference
• Permissions
• Go SDK