Warp-drive state-machine flags

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.

node state-machine.js <subcommand> <project-root> [args] [flags]
node state-machine.js --help [<subcommand>] [--json]

Subcommands

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).

Flags by subcommand

A flag whose parser is kickoff.js is read by the kickoff parser that init embeds (#872); every other flag is read by state-machine.js itself.

init

Flag	Type	Default	Parser	Meaning
--level	int	2	state-machine.js	Automation level (1-4) when -f/--factor is absent.
--issue	string	—	kickoff.js	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).

inject

Flag	Type	Default	Parser	Meaning
--pid	int	the caller's parent pid	state-machine.js	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).

transition

Flag	Type	Default	Parser	Meaning
--data	json	{}	state-machine.js	JSON object merged into state for this transition (issue, branch, check_result, …).

gate

Flag	Type	Default	Parser	Meaning
--session-id	string	—	state-machine.js	The calling session (hook payload session_id). A run another session owns passes with foreign: true and a one-line advisory naming its phase (#2275).

status

Flag	Type	Default	Parser	Meaning
--session-id	string	—	state-machine.js	The calling session; adds owned_by_caller and ownership_basis to the output (#2275).

declared

Flag	Type	Default	Parser	Meaning
--json	bool	false	state-machine.js	Print the rows as JSON instead of a table.
--bob-home	path	$BOB_HOME or ~/.claude	state-machine.js	The BOB_HOME to inspect for hooks and settings.json.

preflight

Flag	Type	Default	Parser	Meaning
--converge	bool	false	state-machine.js	Apply the idempotent bob ready steps first, then re-check; kickoff-only (#1997).

forge-check

Flag	Type	Default	Parser	Meaning
--no-probe	bool	false	state-machine.js	Read only the observations the gh shim recorded; never issue a probe call.

checkpoint

Flag	Type	Default	Parser	Meaning
--data	json	{}	state-machine.js	JSON object; reason is recorded on the checkpoint.
--reason	string	—	state-machine.js	Checkpoint reason when --data carries none.

record-decision

Flag	Type	Default	Parser	Meaning
--data	json	{}	state-machine.js	JSON object carrying description, url and category.
--description	string	—	state-machine.js	What was decided (required unless --data carries it).
--url	string	—	state-machine.js	Link to the decision record.
--category	string	—	state-machine.js	Decision category (reversibility class).

record-sync

Flag	Type	Default	Parser	Meaning
--status	string	unknown	state-machine.js	Sync outcome (noop, synced, conflict, …).
--detail	string	""	state-machine.js	Free-text detail for the sync record.

decisions

Flag	Type	Default	Parser	Meaning
--all	bool	false	state-machine.js	Show the full session history, reviewed decisions included.

abort

Flag	Type	Default	Parser	Meaning
--data	json	{}	state-machine.js	JSON object merged into state for the abort transition.

config

Flag	Type	Default	Parser	Meaning
--cwd	path	the current directory	state-machine.js	Project root whose manifest and settings.local.json layers are resolved.
--json	bool	false	state-machine.js	Print the resolved value (or every key) as JSON.
--sources	bool	false	state-machine.js	config list: also print the layer each value came from - default | fleet-manifest | manifest | settings (#2703).

help

Flag	Type	Default	Parser	Meaning
--json	bool	false	state-machine.js	Print the table as a warp-flags/1 document.

Subcommands that take no flags: verify, graph, budget-decision, segment-decision, decisions-digest, reset.