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 workon the folder with .speccy.yaml, from the current folder up, or else on the current folder.