CLI reference

Every speccoder command and its options, the global flags, the JSON output contract and the exit codes.

speccoder --help lists the daily commands, speccoder help advanced the rest, speccoder help <command> one command. Bare speccoder opens the dashboard at a terminal and prints the report otherwise.

Every command takes:

Every stop and finish ends with a Next: block of commands to copy (next in JSON). Every failure and stop names a code: error[CODE], stopped[CODE] when the run waits for you, warning[CODE] when it worked with less evidence.

Start

Plan

Work

Review

Advanced

JSON output

With --json every command prints exactly one object on stdout and no progress lines, also when the arguments are wrong:

{ "schema_version": 2, "command": "run", "status": "needs_human", "exit_code": 23,
  "message": "T004 needs approval: cargo add unicode-normalization",
  "code": "NEEDS-APPROVAL",
  "fix": ["speccoder report --approvals", "speccoder task approve T004", "speccoder task reject T004 --reason \"…\""],
  "docs": "https://hupe1980.github.io/speccoder/docs/codes/#needs-approval",
  "next": [{ "command": "speccoder report --approvals", "why": "see what waits" }],
  "payload": "run", "data": { … } }

• status is the exit code’s name in snake_case.
• code, fix and docs are present on every result that is not plainly ok, and on an ok with less evidence (REGRESSION-ONLY). Branch on code, never on message.
• fix_steps (beside fix) and every next entry say how an interface takes the line in how: perform (a run speccoder performs, with the input it asks for), view (a read-only view: doctor, report, …), command (the person’s own command as exact argvs; interactive when it reads the keyboard), shell (export …: it must be set where speccoder starts) or words.
• remedy, when present, is a fix speccoder can apply itself: label, effect, the exact command, undo, and whether it writes git history (a commit). Nothing applies it unasked.
• payload names the schema data follows.
• An action (in actions, Needs You and the events) carries an id: its kind (run_task, approve, pull_request, …, or command) and subject. Match actions by id, never by label.
• --help and --version always print text.

Every output has a JSON Schema (draft 2020-12), generated from the code, at https://hupe1980.github.io/speccoder/schemas/v2/<name>.json (offline: speccoder schema <name>). Within a version fields are only added, so ignore fields you do not know; renaming, removing or changing the meaning of a field raises schema_version.

Events

With --events stdout carries only JSON Lines; stderr stays quiet (an approval prompt still appears at a terminal):

{"v":2,"seq":1,"ts":"2026-10-29T10:00:00.000Z","type":"session.started","speccoder":"0.6.1","command":"run","capabilities":["events_v2","approvals_inline"]}
{"v":2,"seq":9,"ts":"…","type":"tool_call","task":"T001","turn":3,"tool":"run_command","target":"cargo test","decision":"allow","ok":true,"tail":[]}
{"v":2,"seq":15,"ts":"…","type":"result","result":{ …what --json prints… }}

Record events (bug.recorded, bug.confirmed, bug.confirm_rejected, bug.outcome, oracle.frozen, oracle.lapsed) have published schemas under events/ (e.g. events/bug.outcome.json).

seq rises by one per line, so a gap means a lost line; a stream without result was interrupted. If the reader goes away, speccoder stops writing and finishes the command. --events with --json is a usage error (USAGE-CONFLICT).

Exit codes

The codes page lists which code exits with which status.

Edit this page