CLI & MCP

Everything the console shows, the terminal can do — and the CLI is the surface agents drive. One rule makes it scriptable: with --json, stdout is exactly one JSON document.

The everyday commands

arthur status              # whole snapshot: queue, sessions, decisions, quota
arthur tick --dry-run      # what should happen next, without writing state
arthur web                 # the console at http://127.0.0.1:7433
arthur watch               # desktop notifications when the loop needs you
arthur notify --message "sprint 2 approved" --dry-run
arthur agents              # which agent CLIs this machine has
arthur usage dashboard     # what each task actually cost

The --json contract

Add --json to any data command: stdout is one JSON document and nothing else. Failures print {"error": "…"} to stderr and leave stdout empty, so "exit 0 ⇒ stdout parses" always holds. Mutating commands return the record they touched — no follow-up read needed.

The queue round trip

arthur queue create --json --job-id BQ-APP-001 --project-id APP \
  --target-chat-title "APP planning" --target-chat-url manual \
  --expected-marker APP_SPRINT_1 --idempotency-key bq-app-001

arthur queue claim  --json --job-id BQ-APP-001
arthur queue submit --json --job-id BQ-APP-001
arthur queue poll-result --json --job-id BQ-APP-001 --marker-found true
arthur queue complete --json --job-id BQ-APP-001

Claims serialize through a browser lock so one advisor conversation happens at a time. If create refuses an idempotency key, the work already exists — find it, do not re-queue it.

Exit codes

With arthur tick --exit-verdict: 0 POLL_DUE · 10 WAIT · 11 HUMAN_INPUT_REQUIRED · 12 BLOCKED_BY_BROWSER_LOCK · 13 BLOCKED_BY_QUOTA. Codes start at 10 so a blocked loop is never mistaken for a broken command:

arthur tick --exit-verdict --json >/dev/null && arthur queue claim --job-id BQ-APP-001

MCP: for clients without a shell

Six workflow tools over stdio, bound to one instance: status, tick, queue_list, queue_create, answer_decision, job_show. They call the same functions the console does, so validation and ledger guarantees are identical. If your client has a terminal, the CLI above is more token-efficient — use it instead.

pip install 'arthur-loop[mcp]'      # needs Python 3.10+

# Claude Code
claude mcp add arthur -- arthur mcp serve

# Codex
codex mcp add arthur -- arthur mcp serve

# OpenClaw
openclaw mcp add arthur --command arthur --arg mcp --arg serve

# Gemini CLI — ~/.gemini/settings.json
# "mcpServers": { "arthur": { "command": "arthur", "args": ["mcp", "serve"] } }