Skip to content

CLI

This page lists each command of the speccy binary, as speccy help prints it. The TUI lists the keys of the terminal UI.

Usage:
speccy [--dir folder] [--addr host:port] [--no-open] Start local mode and open the browser.
speccy serve [--dir folder] [--addr host:port] Start local mode without opening a browser.
speccy serve --hosted Start hosted mode (SPECCY_ environment variables).
speccy init Write .speccy.yaml and ignore .speccy/state/.
speccy add <url> [--profile <key>] Make a GitHub source from a URL, and sync it once.
speccy init --github [--reviewer action|app] Adopt this repo: map its docs, relax the checks that
fail today, and set who reviews pull requests: the
Action, with its workflow, or a hosted Speccy's App.
speccy review <path…> [--format text|json|md] [--summary] [--server URL] [--adopt]
[--stages lint,rubric,grounding,divergence,coherence] [--enforcement advisory|blocking]
Review bundles. Exit codes: 0 Build Ready or advisory,
1 Not Build Ready in blocking mode, 2 usage, 3 run error.
--adopt writes the type and the size the review used
into each doc's frontmatter.
speccy action [--stages …] [--enforcement advisory|blocking] [--verify]
The GitHub Action: review the bundles a pull request
changes, and comment on it. --verify runs the
verification gate instead of the review.
speccy action --work-items --server URL [--enforcement advisory|blocking]
The verify Action of a code repo: verify the work
items a pull request names, scoped to their IDs.
speccy action --pr <pull request URL> --pending | --dry-run [--stages …]
[--levels must,should] [--no-attribution]
Review a pull request from this machine. --pending
posts one review that only you see; --dry-run prints
it and posts nothing. --levels names the levels that
go inline. --no-attribution keeps the name of Speccy
out of the review.
speccy review-prs <pull request URL>... | --repo <owner/name> [--requested]
[--parallel N] [--again] [--yes] [--stages …] [--levels must,should]
[--no-attribution]
Review many pull requests. Each one gets a pending
review that only you see. --repo takes each open
pull request that is not a draft and changes a spec
doc; --requested keeps the ones that ask for your
review. A pull request reviewed at its head commit
is skipped, unless --again.
speccy review-prs --batch <ID> | --cancel <ID> Show a batch until it ends, or start no new pull
request of it.
speccy ask <pull request URL> "<concern>" [--section "A › B"] [--force] [--no-attribution]
Turn your concern into one question for the author,
on its section, in your pending review.
speccy pending list <pull request URL> List the comments of your pending review.
speccy pending delete <pull request URL> <ID>... Delete comments of your pending review.
speccy pending discard <pull request URL>... | --repo <owner/name> | --batch <ID>
Discard your pending reviews.
speccy tui Open the terminal UI.
speccy mcp [--root folder] Run the MCP server over stdio.
speccy profile validate <file> [--conflicts] Check a profile file. --conflicts asks the reviewer
model for checks that pull against each other.
speccy export <path> --format zip|html Export a bundle, or its HTML report.
speccy handoff <path> --out <folder> Write a bundle's build packet for a coding agent.
[--label <name>] [--acknowledged]
speccy breakdown propose|show|edit|update|readers|push|export <path>
Propose, check, edit and push a breakdown of a
Build Ready doc into epics and work items. Run
speccy breakdown for the flags of each step.
speccy work-item <issue URL, key or bundle/item> [--server URL] [--json]
Print the slice of the spec one work item builds,
at the version it was pushed from.
speccy report <path> --handoff <id> --text <text> Report what a build learned about the doc.
[--blocked | --note] [--section "A › B"] [--trace-id REQ-012]
speccy waive <doc path> <finding ID> --reason "<reason>" [--approve]
[--upstream-change | --send-back] Ask for a waiver of one finding. The finding ID is
from speccy review --format json. --approve also
approves it, as the profile's waiver policy allows.
--upstream-change answers a conflict: the linked
doc must change. --send-back answers a downstream
request: the downstream doc must change.
speccy waivers list <doc path> List the waivers of a spec doc, with their status.
speccy verify <path> [<GitHub URL or folder>] Verify one build against the bundle. With no URL,
[--trace-ids REQ-1,REQ-2 | --work-item <issue>]
the repo the doc's implemented-by link names.
--trace-ids or --work-item verifies those IDs only.
speccy admin invite --role admin|member Print an invite link (hosted).
speccy admin reset-link <email> Print a password reset link (hosted).
speccy version Print the version.
Local mode serves the bundles under --dir (default: the current folder). The other commands work
on the folder with .speccy.yaml, from the current folder up, or else on the current folder.