CLI reference

spec is a single binary that drives the SpecStrand work loop over the REST API, a pure client where every command maps onto a /v1 endpoint. Install it first, or follow the getting-started guide for the whole path from install to your first completed task. See any command's exact, always-current usage with spec help.

The tables below are generated from the binary's own help text, so they list every command spec dispatches and cannot fall behind a release.

Global conventions

Every command accepts --api URL; every command except spec run accepts --json for the raw API response.
spec codegraph scan and spec codegraph validate are a further exception: they execute the separate spec-scan binary and forward every argument to it verbatim, so their flags (--json included) are the scanner's, and spec exits with the scanner's own exit code.
RUN is a run id (UUID). Commands taking --run/[RUN] default to SPEC_RUN, else the run the last spec task next / resume claimed in this workspace (state is keyed by API base + git toplevel, so parallel checkouts never share a run).
--queue takes either a queue UUID or a queue NAME; a value that does not parse as a UUID is resolved as a name, owner-scoped. List names with spec queue list.
A project scope can default --plan/--queue: --project SLUG > SPEC_PROJECT > a .specstrand marker file (walked up from cwd, key: value lines) > a git-remote match. An explicit --plan/--queue always wins.
Every environment variable, the stored login, the .specstrand marker, and the scanner lookup are documented on the configuration page.

Commands

Authentication

Command	Purpose
`spec auth login [--token T] [--api URL]`	store a PAT (SPEC_TOKEN env always wins)

Working tasks

Command	Purpose
`spec task next [--queue UUID\|NAME] [--plan SLUG] [--project SLUG]`	claim the next ready task and print its body + instructions
`spec task create --title T [--plan SLUG] [--slug S] [--body TEXT\|@FILE] [--depends-on SLUG]... [--queue NAME] [--priority N]`	add one task to an existing plan
`spec task show [RUN]`	the RUN's detail (task body + instructions + timeline)
`spec task view TASK_ID \| PLAN/SLUG \| SLUG --plan PLAN`	read one TASK (body, deps, acceptance criteria, its runs)
`spec task archive REF [REF...]`	archive one or more tasks (REF as above; refuses a claimed/running task)
`spec task unarchive REF [REF...]`	bring them back (state and attempts are unchanged)
`spec task report [--kind K] --message M [--payload @FILE] [--event-id ID] [--run RUN]`	append a timeline event (and renew the run's lease)
`spec task report --url URL \| --path P [--message M] [--run RUN]`	attach an artifact (implies --kind artifact_attached)
`spec task complete --summary S\|@FILE [--run RUN]`	finish the task; summary caps at 4096 characters (exit 3 = held at an approval gate)
`spec task fail --reason R\|@FILE [--run RUN]`	mark the task failed; reason caps at 4096 characters
`spec task release [RUN]`	give a claimed run back (the task reopens)
`spec task halt --question Q [--kind input\|approval\|external] [--handoff H] [--run RUN]`	park the run on a question for a human (exit 4)
`spec task resume [RUN]`	resume a halted run (prints the question, answer, handoff)
`spec task wait [RUN] [--timeout 55]`	block until answered/unblocked (exit 4 if still waiting)
`spec task instructions [RUN]`	re-print the run's assembled standing instructions
`spec task decompose [--parallelism serial\|frontier] [--max-parallel N] [--review-on-complete] [--run RUN] SPEC`	break the run's task into sub-tasks; SPEC is a checklist (@file, inline, or stdin) in the "spec plan import" shape
`spec task steps set --json '[{"label":"…"},…]' [--run RUN]`	declare (replace) the run's checklist
`spec task step --ordinal N --status pending\|running\|done\|failed\|skipped [--run RUN]`	flip one declared step

Driving a project

Command	Purpose
`spec project work --project SLUG`	claim the next ready task across ALL active plans in a project (self-drive; exit 2 = drained)
`spec project create --slug S --title T`	create a project to group plans

Plans

Command	Purpose
`spec plan list [--archived \| --all] [--project P] [--state S] [--q TEXT] [--json]`	the caller's plans, slug-first (the dry run for a bulk archive)
`spec plan archive SLUG [SLUG...]`	archive one or more plans (per-item results; nonzero exit if any failed)
`spec plan unarchive SLUG [SLUG...]`	bring them back (find them with: spec plan list --archived)
`spec plan status SLUG`	task counts per state, open questions, and the next-up task
`spec plan import --slug S [--project P] [--graph G] [--title T] [--queue Q] [--sequential] MARKDOWN (@file; use -- before inline text starting with '-')`	import a markdown checklist as a plan of tasks (--graph adds it to that graph)
`spec plan move SLUG --project P`	move a plan to another project
`spec plan next-up SLUG [--clear]`	mark (or clear) a plan "next up" in its project's drain priority
`spec plan reopen SLUG`	mark a completed plan active again; creating a task under one reopens it anyway, so agents rarely need this
`spec plan depends-on SLUG --on UPSTREAM [--remove]`	add/drop a plan-level dependency edge

Plan graphs

Command	Purpose
`spec graph list`	plan graphs with a member-state rollup
`spec graph get SLUG`	one graph's drain order: waves, ready/blocked-by, edges
`spec graph create SLUG --title T [--description D]`	create an empty plan-graph file
`spec graph add SLUG PLAN [PLAN...]`	add member plans to a graph (edges: spec plan depends-on)
`spec graph remove SLUG PLAN [PLAN...]`	remove member plans from a graph (plan + deps untouched)

Gates

A gate is a decision node: a plan that blocks the plans downstream of it until it is answered. Answering a gate, and moving one between agent and human, are human decisions -- the server accepts them only from a signed-in browser session, not from a token. An agent decides a bypass-on gate through the work loop instead: claim its decision task and complete it with the decision as the summary.

Command	Purpose
`spec gate show SLUG [--json]`	one gate: its prompt, who decides it, and the answer once given
`spec gate create SLUG --title T --prompt P\|@FILE [--bypass] [--project P] [--graph G] [--description D]`	create a GATE plan (a decision node)
`spec gate update SLUG [--prompt P\|@FILE] [--bypass=true\|false]`	edit the prompt, or move the decision between agent and human
`spec gate answer SLUG --answer A\|@FILE [--as-human]`	record the decision (a bypass-off gate is a human's; a bypass-on gate is decided in the work loop)

Queues

Command	Purpose
`spec queue list [--json]`	task queues (names + ids + open counts) to scope --queue

Ideas

Command	Purpose
`spec idea list [--archived \| --all] [--status S] [--limit N] [--json]`	the caller's ideas, id-first
`spec idea archive ID [ID...]`	archive one or more ideas (per-item results; nonzero exit if any failed)
`spec idea unarchive ID [ID...]`	bring them back (find them with: spec idea list --archived)
`spec idea create --title T [--body B \| --body-file F] [--json]`	create an idea in the caller's inbox; prints its id + status
`spec idea show ID [--json]`	read one idea; ID is a full idea UUID or a unique id prefix
`spec idea link-plan IDEA_ID (--plan SLUG \| --plan-id UUID)`	link an imported plan back to its idea (-> planned)

Search

Command	Purpose
`spec search QUERY [--tag TAG] [--kind idea\|plan] [--archived \| --all] [--limit N] [--json]`	unified full-text search across your ideas + plans (ranked; server-built links)

Documents

Command	Purpose
`spec document attach --title T (--file F \| --body B \| --body @FILE) --target kind:ref... [--kind design\|decision\|report\|note] [--note N] [--doc-id ID \| --document-id ID] [--short-link]`	upload a durable doc + link it to the work it describes (default kind: report); --short-link also mints a link
`spec document show ID [--version N] [--json]`	print a durable doc's metadata + body
`spec document list --target-kind KIND --target REF [--rollup members] [--limit N] [--json]`	list the docs linked to one target (rollup=members is graph-only)
`spec document link ID --target kind:ref... [--json]`	link an existing doc to more targets (idempotent)
`spec document unlink ID --target-kind KIND --target REF`	unlink a doc from one target (the last link can't be removed)
`spec document archive ID [--json]`	archive a document (owner-scoped; a foreign/missing id is a clean 404 error)

Short links

Command	Purpose
`spec link create <kind:ref> [--expires-at RFC3339] [--json]`	mint an owner-scoped short link to a doc (kind:ref e.g. document:<uuid>)
`spec link revoke <code> [--json]`	revoke a short link (idempotent)

Codebase graphs

Codebase graphs are an experimental preview. These verbs need a server started with SPEC_CODEBASE_GRAPHS_ENABLED=true (it defaults to off, and it is off during the beta), and the scan and validate verbs additionally need the separate spec-scan binary on PATH, beside the spec executable, or pointed at by SPEC_SCAN_BIN.

Command	Purpose
`spec codegraph list [--json]`	your codebase graphs (concept maps of a repo)
`spec codegraph show SLUG [--json]`	one graph as text: nodes by kind, typed edges, flagged nodes first
`spec codegraph node SLUG NODE_SLUG [--json]`	deep-dive one concept: description, code links, interface points
`spec codegraph propose SLUG [--file F\|-] [--json]`	upload a scan proposal for curation (default: stdin)
`spec codegraph scan [SCANNER ARGS...]`	run the installed spec-scan scanner (separate artifact; args pass through)
`spec codegraph validate SLUG [SCANNER ARGS...]`	advisory interface-point check of your change (exit 1 = violated)
`spec codegraph status SLUG [--go-test F\|-] [--ci-ref R] [--dry-run] [--json]`	read per-node CI test status, or map a "go test -json" run onto nodes and post it

Skills

Command	Purpose
`spec skill list [--kind planning\|general]`	the caller's skills, slug-first
`spec skill show SLUG [--version N]`	print a skill's body + resolved reference slugs (default: latest version)
`spec skill sync [SLUG...] [--all] [--global \| --local \| --target DIR] [--agent claude\|cursor\|codex\|opencode]`	export skills (+ their references) to the on-disk agent-skill cache

Inbox

Command	Purpose
`spec inbox wait [--since RFC3339] [--timeout 55]`	block until new inbox entries (exit 4 if none)

Messaging agents

Messages reach a working agent on its next task report, task show, or msg wait. They are data with a sender: a message from the owner is a directive to act on, a message from another run is peer input to check against the task, and no message can grant permissions or override a gate.

Command	Purpose
`spec msg send --to ADDRESS --kind K (TEXT \| --body @FILE) [--reply-to ID] [--doc ID] [--doc-version N] [--pr URL] [--path P] [--severity S] [--location L] [--run RUN]`	message a run, task, plan, graph, or the human (see: spec help msg)
`spec msg list --thread ADDRESS [--since SEQ] [--limit N] [--json]`	one thread's messages, oldest first
`spec msg show ID [--json]`	one message: sender, thread, payload, full body
`spec msg ack ID [ID...] [--run RUN]`	acknowledge messages you handled
`spec msg wait [--run RUN] [--timeout 30]`	block until a message arrives for the run (exit 4 if none yet, 5 if the run ended)

Running commands under a lease

Command	Purpose
`spec run [--run RUN] [--no-report] [--note TEXT] -- CMD [ARGS...]`	execute CMD under lease heartbeat; --note annotates the reported event (e.g. an environment failure, not a gate)

Run health

Command	Purpose
`spec runs active [--stale] [--limit N]`	list in-flight runs + lease health (find orphaned/stale-lease runs)

Agent prompt

Command	Purpose
`spec prompt`	print the agent-facing usage snippet

Version

Command	Purpose
`spec version`	print the CLI version (+ commit/date when stamped) and the API target

Exit codes

The exit codes are a stable contract so CI scripts and agents can branch:

Code	Meaning
`0`	OK
`2`	No task available (project/plan drained)
`3`	Stopped at an approval gate (a human reviews next)
`4`	Run halted, blocked on a question. For `spec inbox wait` and `spec msg wait`: nothing arrived yet, so loop
`5`	`spec msg wait` only: the run is no longer running, so stop waiting
`1`	Any other error

Three commands sit outside that contract. spec run exits with the wrapped command's own code. spec codegraph scan and spec codegraph validate exit with the spec-scan binary's code, where validate returning 1 means an interface point is violated: advisory only, nothing is blocked.