Commands reference
The specweave CLI is the source of truth. Skills such as /sw:do or $sw-handoff call these commands and add the judgement steps; see the skills reference.
Most commands that take an increment id accept the short number (0042) and fall back to the single active increment when you leave it out. Run specweave <command> --help for the full flag list.
Global options
| Option | What it does |
|---|---|
--workspace <root> | Run the command in this planning workspace, for example the umbrella folder that holds repositories/<org>/<repo>, wherever you start it from. SPECWEAVE_WORKSPACE=<root> does the same, but only when the current folder is inside that workspace or one of its registered repositories. |
--version, -V | Print the CLI version. |
The loop
| Step | Command |
|---|---|
| Start a session | specweave pickup |
| Plan | specweave create-increment "Add login form" |
| Work | specweave task next, task claim T-01, task done T-01 --run "npm test" |
| Check | specweave verify |
| Close | specweave complete 0042 |
| Stop | specweave handoff --reason "out of tokens" |
Setup
| Command | Purpose | Useful flags |
|---|---|---|
specweave init [project-name] | Set up .specweave/, AGENTS.md, CLAUDE.md and the skills for your tool. | -a, --adapter <tool>, -q, --quick (no prompts), -f, --force (fresh start), -l, --language <lang>, --tech-stack <language> (passed to the tool adapter, such as nodejs or python), --git-hooks. -t, --template and --full are still accepted and change nothing in 3.x. |
specweave update | Update the CLI, instruction files, config and plugins in one step. This is the upgrade path from 2.x. | --check (dry run), --no-self, --no-plugins, -f, --force |
specweave update-instructions | Rewrite AGENTS.md and CLAUDE.md with a merge that keeps your own sections. | --dry-run, -v, --verbose |
specweave refresh-plugins | Reinstall the SpecWeave skills for the configured tool. | --force, --plugin <name>, -q, --quiet |
specweave skills [list|enable|disable] [names...] | List the project's skills (seven core, four optional) and why each optional one is on or off, or turn optional ones on or off: specweave skills enable glossary sync. Writes skills.enabled or skills.disabled and reinstalls the project copies. Core skills cannot be disabled; naming one in enable, such as grill-me, only prints that it is core. | --json |
specweave uninstall | Remove SpecWeave from the project. | --keep-data (archive .specweave/), --dry-run, --global, -f, --force |
Increments
| Command | Purpose | Useful flags |
|---|---|---|
specweave create-increment [title] | Create .specweave/increments/NNNN-slug/ with metadata.json and spec.md. The number is reserved atomically. | --with-plan (also plan.md), --planned (create as planned, not active), --no-commit (skip the git.autoCommitIncrement commit), --supersedes <id>, --parent <id>, --type <type>, --priority <P1|P2|P3>, --json |
specweave next-id | Print the next free increment number. Prefer create-increment. | --name <slug>, --project <id> |
specweave start <id> | Move a planned or paused increment to active. | |
specweave pause <id> | Pause an active increment. | -r, --reason <text> |
specweave resume <id> | Resume a paused, abandoned or not-yet-started increment. | |
specweave abandon <id> | Abandon an increment. | -r, --reason <text>, -f, --force |
specweave --workspace <root> reopen <id> | Move a completed increment back to planned when it was closed too early. It never activates the increment; run specweave start <id> for that, once there is capacity. It refuses without a reason or an explicit workspace, for any status other than completed, and while another agent holds a claimed, stale or blocked task. The old closure is kept in metadata.reopened, and the ledger and reports are unchanged. | -r, --reason <text> (required), --json |
specweave complete [id] [more-ids...] | Close one or more increments. Blocks without a passing reports/verify.json unless you give a reason. Alias: done. | -r, --reason <text>, --all --reason <text> (close every task-complete increment), -y, --yes |
specweave status | Status overview of all increments. Alias: progress. | -v, --verbose, -t, --type <type> |
specweave archive [increments...] | Move completed increments to the archive folder. | --keep-last <n> (default 5), --older-than <days>, --archive-completed, --dry-run |
specweave check-discipline | Status counts, the advisory WIP note and metadata consistency. | --json, -v, --verbose |
Status changes never call GitHub, Jira or Azure DevOps. See increment status reference for the states.
Tasks and verification
specweave task <action> [task] [increment] works the append-only ledger. Task definitions live in the ## Tasks section of spec.md (or a legacy tasks.md); state lives only in ledger.jsonl.
| Action | Purpose |
|---|---|
task whoami | Print this agent's id, such as claude@laptop or codex@cloud. |
task list | Every task with status, owner and evidence. --json for scripts. |
task next | The first open task whose dependencies are done and whose files no one else holds. Prints the task with the text of its acceptance criteria. |
task claim T-01 | Claim a task. Exit 3 means someone else holds it, 4 means a file overlap with a live claim, 6 means unmet dependencies. --force overrides. |
task done T-01 --run "<cmd>" | Run the task's test, store the exit code and output tail as evidence, and mark it done. Exit 5 when the command fails. The full output goes to reports/task-T-01.txt. --evidence "<text>" if you already have proof. |
task release T-01 | Give a claim back. --all-mine releases every claim you hold. |
task block T-01 --reason "<why>" | Mark a task blocked. |
task skip T-01 --reason "<why>" | Mark a task as not needed. Final; the reason is required. |
task render | Print the task board. --write refreshes a legacy tasks.md. |
With git.autoCommitIncrement on, claim, done, release, block and skip then commit the increment's spec.md, ledger.jsonl and metadata.json (never evidence/ or reports/) as NNNN: <action> T-xx, through a pathspec so your other staged changes stay staged. card start|done|wait T-NN does the same. git.autoPushIncrement also pushes it, fast-forward only, to a same-named upstream and only when nothing else is unpushed. A commit that cannot happen is one warning and exit 0; --no-commit (on task and card) skips it.
| Command | Purpose | Useful flags |
|---|---|---|
specweave verify [id] | Run the project's test, lint and build commands and write reports/verify.md and reports/verify.json. verify.json is what complete checks. | --cmd <command> (repeatable), --json |
specweave review [id] | Cross-model adversarial review. It reads from the ledger which model family wrote the code and runs a reviewer from another one: Codex with GPT-6.1-Sol in a read-only sandbox for Claude-written code, Claude Opus for code written by OpenAI models. Writes reports/review-<reviewer>.md and a ledger note. Exit 0 means ship; 3 means fix first, or the reviewer gave no verdict; 1 means an error, such as no reviewer installed. Reviewers and defaults are in review. | --brief (print the brief to paste into any model; runs nothing), --reviewer <name>, --base <ref>, --timeout <minutes> (default 30), --json |
specweave glossary [check|list] | check (the default) compares GLOSSARY.md with the code: avoided words used as identifiers, with file:line, and backticked Data or Code names that no longer exist. list prints the terms. Exits 0, or 1 with --strict when check finds anything. | --strict (for CI), --json |
specweave qa <id> | Risk-scored quality assessment. It is not the review and not the closure gate. | --gate, --pre, --ci (exit 1 on fail), --no-ai |
specweave generate-rubric <id> | Write or refresh rubric.md, a quality contract tied to the acceptance criteria. | --refresh |
Handoff
| Command | Purpose | Useful flags |
|---|---|---|
specweave handoff [id] | Release your claims, record the handoff in the ledger, write handoff.md plus handoff.diff with secrets scrubbed, and push. The push sends the branch and a snapshot of uncommitted edits to the specweave-handoff ref and wip/<branch>, so any tool, machine or account can pick it up. Without a git remote the push is skipped. With git.autoCommitIncrement on, it first commits the increment's spec.md, ledger.jsonl, metadata.json (and handoff.md when tracked) as NNNN: handoff, so the branch push carries them. | --reason <text>, --next <step>, --no-push (keep it local), --no-commit, --summary <text>, --decision <text> (repeatable), --gotcha <text>, --keep-claims, --inline, --json |
specweave handoff --all | Write .specweave/handoffs/<date>-INDEX.md and index.json: one row per active increment (tasks, open ACs, last activity, what it waits on, a resume prompt) and every nested checkout (repositories/<org>/<repo> or any folder up to three levels down with its own .git) with uncommitted files, unpushed commits or a branch with no remote, with its open PR via gh. Writes nothing else; never commits or pushes. A hand-written handoff.md is never overwritten: the generated doc goes to handoff.auto.md, and <!-- keep --> blocks survive regeneration. | --reason <text>, --dry-run (print, write nothing), --out <dir>, --json |
specweave pickup [id] | Fetch the latest handoff and apply it to this checkout: fast-forward the branch and restore the uncommitted edits, only when the working tree is clean and the history allows it; otherwise it explains why and changes nothing. Then print the open increment, the next task with its criteria, claims, branch state, notes and the memory index. Records a pickup event in the ledger. | --no-apply (only show the waiting handoff), --all (print the newest handoff --all index, actionable increments first; changes nothing), --json |
specweave report [id] | Write an HTML timeline of who did what on an increment: tools, sessions, handoffs, pickups and task evidence. Default output reports/handoff-report.html; handoff and pickup refresh it too. | --out <file> |
specweave note "<text>" [id] | Leave a message in the increment's ledger. pickup shows it to whoever comes next. | |
specweave auto-handoff <on|off|status> | Act near the usage limit, on your own machine. In suggest mode (default) a session at the threshold tells you once that you can say "hand off" and keeps working; in enforce mode it runs specweave handoff and stops; in checkpoint mode it only saves local checkpoints. Nothing happens at the threshold when the full windows reset within --wait-under minutes. on sets Claude Code's status line to specweave statusline, adds a specweave usage-guard Stop hook to Claude Code and, when ~/.codex exists, to Codex, and a usage-guard --limit-hit StopFailure hook to Claude Code and Grok Build. status shows the mode, which hooks are in place and the last usage each tool reported. off restores your previous setup. Rules: auto-handoff. | --mode <suggest|enforce|checkpoint>, --at <percent> (default 95), --wait-under <minutes> (default 30), --checkpoint-only, --handoff |
specweave autocompact <on|off|status> | Where Claude Code summarizes a long session. on writes autoCompactWindow (default 400000) to ~/.claude/settings.json; off removes it; status shows the window Claude Code will use, its source, per-model /autocompact values and Codex's model_auto_compact_token_limit. init writes 400000 to the new project's .claude/settings.json. Guide: auto-compact. | --at <tokens> (100k to 1M), --project |
specweave statusline | The Claude Code status line auto-handoff on installs. It records the 5-hour and 7-day usage, and keeps showing your previous status line. | --wrap <command> |
specweave usage-guard | The Stop hook auto-handoff on installs. Once usage passes the threshold, it gives the agent a heads-up for you (suggest) or asks it to run specweave handoff (enforce), once per session and usage window. | --limit-hit (StopFailure: hand off now, the turn hit the limit) |
See cross-tool handoff for the full flow.
Inside a SpecWithCode thread, every ledger write (task claim, task done, task block, task skip, task release, auto-claim, pickup, note and handoff) also records the thread's increment in ~/.specweave/studio/threads/<thread>.json. SpecWithCode reads it to show the thread's plan card. The file lives outside the repository, holds no task state, and a failed write never fails the command (since 3.0.18).
Autonomy
| Command | Purpose | Useful flags |
|---|---|---|
specweave auto [ids...] | Start unattended execution. The Stop hook feeds the session back into the loop until the tasks are done. | --dry-run, --all-backlog, --reset |
specweave auto-status | Status of the running auto session. | --json, --verbose |
specweave cancel-auto | Stop the auto session. | --force |
specweave team [description] | Launch Claude Code with agent teams in split panes. | --mode <tmux|in-process>, --no-increment |
specweave jev <action> | Jev (System One) for closed-set decisions: doctor, setup, ask, route, task, guard, screen, failure, browse, usage. | --json, --provider <name> (setup) |
See autonomous execution, agent teams and Jev.
Sync
| Command | Purpose |
|---|---|
specweave sync push [id] | Push progress to the configured tracker. The only command that writes to one. |
specweave sync pull | Report tracker changes, or import issues as increments. |
specweave sync status | Token, account, provider health and sync gaps. |
specweave sync setup | Connect GitHub, Jira or Azure DevOps. |
specweave link-pr --increment <id> --pr-url <url> --pr-number <n> | Link a pull request to the increment's Jira or Azure DevOps ticket. |
specweave branch-name <id> | Print the branch name for an increment, including a ticket key when one is linked. |
Flags are in the specweave sync reference.
Maintenance
| Command | Purpose | Useful flags |
|---|---|---|
specweave doctor | Project health check: config, instruction files, hooks, installation. | --fix, --fix-status (repair metadata.json and spec.md status mismatches), --quick, --json |
specweave gc | Find stale .specweave/state files and report worktree size. Dry run by default. | -y, --yes (delete), --json |
specweave hooks log | Recent hook warnings, errors and blocks from .specweave/logs/hooks.jsonl. | --last <n>, --blocks-only, --errors-only, --hook <name> |
specweave dashboard | Open the local dashboard in the browser. | -p, --port <n> (default 3456), --no-browser |
Other
| Command | Purpose | Useful flags |
|---|---|---|
specweave save [message] | Generate a commit message, commit, sync with the remote and push. | --dry-run, --no-push, --sync <rebase|merge|none>, -i, --interactive |
specweave lsp <action> | Code intelligence: refs, def, hover, symbols, search, warmup, status, setup. See LSP integration. | |
specweave get <source> | Clone a repository into the workspace and register it. Accepts owner/repo, a URL, or an org with --all. | --branch <name>, --all, --pattern <glob>, --no-init |
specweave context projects | Print the project and board values an increment can use. | |
specweave project <action> | Portable project hub: init, show, set, brief, work-add, work-update, work-record, artifact-add, artifact-remove, routine-add, routine-remove. See portable projects. | --harness <codex|claude|generic>, --json |
Removed in 3.0
These commands no longer exist. Living docs are optional and off by default; with livingDocs: "onDone" in config they regenerate when an increment closes, with no command of their own.
living-docs, jobs, sync-living-docs, docs, the sync-progress, sync-retry, sync-status, sync-health, sync-gaps and sync-setup aliases (use specweave sync), validate-jira, analytics, analytics-push, cache, commits, interview, decision-log, export-skills, detect-intent, detect-project, scan-skill, scan-plugins, judge-skill, session, health (use doctor), status-line, evaluate-completion, install, list, hook, resolve-structure, migrate-to-umbrella.
See SpecWeave 3.0 for why they went and what replaces them.