Every subcommand and flag state-machine.js accepts is declared once in scripts/warp-drive/flags.json (warp-flags/1, #2085). parseFlagArg resolves through that table — reading an undeclared flag throws — and an undeclared flag on the command line is refused with exit 2. --help or -h anywhere prints the table instead of running the subcommand; bob warp --help appends the same text. What the phases and transitions mean: Warp-Drive State Reference. What the kickoff flags do to a run: Kickoff Flags.
21 subcommands, 37 flags — generated from the flag registry.
Subcommand
Arguments
Flags
Purpose
init
<project-root>
14
Create a new session and transition to prerequisites; refuses while a live, non-stale session exists.
inject
<project-root>
2
Print the resumed phase context for the SessionStart hook and re-anchor identity to this segment (exit 2 = no session).
transition
<project-root> <event>
1
Fire <event> from the current phase; an event the phase does not allow is refused (exit 1).
gate
<project-root> <operation>
1
Is <operation> (e.g. git_commit) allowed in the current phase?
verify
<project-root> <event>
0
Run the verification gates declared for <event> (e.g. code_complete).
status
<project-root>
1
Print the current state as JSON (exit 2 = no session).
graph
[<project-root>]
0
Print the static phase/transition topology; the project root is optional.
declared
<project-root>
2
List the declared automatic behaviours and whether each hook is present and wired (exit 3 = a promise cannot be kept, #1834).
preflight
<project-root>
1
Run the preflight gate and let the engine fire preflight_ok / preflight_failed (preflight phase only, #1923).
budget-decision
<project-root>
0
L4 bounded auto-continue verdict for a budget_exceeded halt (exit 0 = may continue, 3 = halt, #873).
forge-check
<project-root>
1
Read the forge signal (probing it), record degraded mode on state.forge, and resume a run parked on the forge once it is operational (exit 0 = normal or resumed, 3 = degraded or still parked, #1751).
segment-decision
<project-root>
0
Should the run segment at this awaiting_continue boundary? (exit 0 = segment, 3 = keep going, #870).
checkpoint
<project-root>
2
Record a segmentation checkpoint at awaiting_continue; keeps state and phase, refuses over in-flight work (#2037).
record-decision
<project-root>
4
Append an auto-decision to state.decisions[] and count it against max_auto_decisions (#876).
record-sync
<project-root>
2
Record a stream-freshness sync result on state.stream_sync (#1178).
decisions-digest
<project-root>
0
Print the session-end decisions digest (markdown) from state.decisions[] (#877).
decisions
<project-root>
1
Print the auto-decision log as JSON; the unreviewed window by default (#876).
abort
<project-root>
1
Shorthand for transition <project-root> abort.
reset
<project-root>
0
Delete the state file immediately — no cleanup.
config
get <key> | list | keys
3
The _workflow config table as a CLI (#2041); takes –cwd, not a positional project root. An undeclared key is refused (exit 2).
help
[<subcommand>]
1
Print this table; also answered by –help or -h anywhere on the command line (#2085).
Issue scope: one issue number or a comma-separated list (#992); the run never widens beyond it.
--requirement
string
—
state-machine.js
Legacy requirement reference recorded on session.requirement.
--pid
int
the caller’s parent pid
state-machine.js
The Claude Code REPL pid that owns the session (pass $PPID).
--session-id
string
$CLAUDE_CODE_SESSION_ID
state-machine.js
The Claude session that owns the run, recorded on session.session_id (#2275); the commit gate and stop hook compare hook payloads against it.
--work-type
req | bug | task
req
state-machine.js
bug selects the bug-fix loop semantics (#518), task the maintenance loop whose DoD is the issue’s Verification checklist (#1959); anything else is a requirement.
--factor, -f, factor
int
—
kickoff.js
Automation level for the run (1-4); wins over –level (#872).
--timeout
int
—
kickoff.js
Decision-response timeout in minutes; 0 = work around or stop.
--ceiling
pr | external | test | prod
—
kickoff.js
Promotion ceiling — the run never deploys past it.
--budget
number
—
kickoff.js
Session cost ceiling in USD, enforced by the session breaker.
--max-tokens
int
—
kickoff.js
Session token ceiling, enforced by the session breaker.
--area
string
—
kickoff.js
Area scope: restrict discovery to one area:<slug> workstream.
--flightplan
int
—
kickoff.js
Flight-plan scope: consume plan issue <N> in order (#1068); lifecycle-gated at kickoff (#1667); a plan waiting on a predecessor ends init cleanly with a note, no run (#2298).
--dry-run
bool
false
kickoff.js
Pre-flight only: pre-classify decisions and emit TODOs, author nothing (#878).
The resumed segment’s REPL pid (the inject hook passes $CLAUDE_PID when the harness exports it, else $PPID).
--session-id
string
—
state-machine.js
The starting session’s id (hook payload session_id). A session that may not take the run over — another live owner, no pending checkpoint handoff — gets a one-line advisory and re-anchors nothing (#2275).