Usage
Every command takes --root DIR; without it spec17 uses the nearest parent folder that holds specs, else the nearest Git work tree. The commands that print a result (all but serve, install and uninstall) also take --json.
| Command | What it shows |
|---|---|
spec17 report | Whole-project status: coverage, problems, where to look next |
spec17 status | Requirements by state; --missing, --issues, --done, --unproven, --built, --all |
spec17 status --changed [REF] | Requirements the working tree (or a ref) touches; --staged, --no-untracked, --ignore-whitespace |
spec17 trace ID | One requirement: spec text, tests, citations, related code |
spec17 changes, diff, history | What changed against a ref, one changed file by hunk, commits not on the base branch |
spec17 overlap, uncovered | Code covered by two or more requirements, where specs may conflict or complement each other; code no requirement covers. Candidates, not verdicts (need a CodeGraph index) |
spec17 doctor [--fix] | Checks the setup; --fix runs codegraph init or sync |
spec17 install, uninstall | The agent skill and MCP entries, see Agents |
spec17 status --missing # due requirements with no test
spec17 trace SCAN-01 # one requirement
spec17 changes --ref main # against a ref
spec17 report --json --root ../other # JSON for another repo
Dashboard #
spec17 with no command is spec17 serve: it starts the server on 127.0.0.1:7411 for the repo in the current directory (or --root) and opens the dashboard. The server options belong to serve: spec17 serve --port N changes the port, --no-open skips the browser, and --ui-port N serves the dashboard on its own port while --port keeps only /mcp. The server binds to localhost only and rejects unknown Host and Origin values.
The URL is the view, so back/forward, reload and shared links work: /changes, /modules, /tests, /requirements/ID, /requirements?view=docs, /code, /overlap, /uncovered, /settings.


CodeGraph #
An optional CodeGraph index (.codegraph/codegraph.db, opened read-only) adds test-to-code links, overlap and uncovered-code analysis. Without it report and the dashboard say “not checked” or “not available”, and everything else works. The commands and tools that need the index (spec17 overlap, uncovered, status --overlap, status --uncovered, and the matching MCP tools) fail with “no .codegraph index here” instead: the CLI exits 1, the tools return an error. spec17 doctor --fix or the dashboard’s Settings tab can create or refresh it, only when you ask.
Build from source #
make build # target/release/spec17, UI embedded
make install # into ~/.cargo/bin
make dev # Vite dev server (hot reload) + Rust server
make report # text report for ROOT (default: this repo)
SKIP_WEB_BUILD=1 skips the UI build when web/dist already exists. The README has releases and dev builds.