CLI Reference

Table of contents

1. Usage
2. Commands
   1. check
   2. coverage
   3. generate
   4. score
   5. mcp
   6. init
   7. watch
3. Flags
4. Exit Codes
5. JSON Output
   1. Check
   2. Coverage

---

Usage

specsync [command] [flags]

Default command is check.

---

Commands

check

Validate all specs against source code.

specsync check                          # basic validation
specsync check --strict                 # warnings become errors
specsync check --strict --require-coverage 100
specsync check --json                   # machine-readable output

Three validation stages:

1. Structural — required frontmatter fields, file existence, required sections
2. API surface — spec symbols vs. actual code exports
3. Dependencies — depends_on paths, db_tables against schema

coverage

File and module coverage report.

specsync coverage
specsync coverage --json

generate

Scaffold spec files for modules that don’t have one. Uses specs/_template.spec.md if present.

specsync generate                       # template mode — stubs with TODOs
specsync generate --provider auto       # AI mode — auto-detect provider, writes real content
specsync generate --provider anthropic  # AI mode — use Anthropic API directly

With --provider, source code is piped to an LLM which generates filled-in specs (Purpose, Public API tables, Invariants, etc.). Use --provider auto to auto-detect an installed provider, or specify one by name (anthropic, openai, command). The command provider resolves from: aiCommand in config → SPECSYNC_AI_COMMAND env var → claude -p --output-format text. See Configuration for aiCommand and aiTimeout.

score

Quality-score your spec files on a 0–100 scale with per-spec improvement suggestions.

specsync score                          # score all specs
specsync score --json                   # machine-readable scores

Scores are based on a weighted rubric: completeness, detail level, API table coverage, behavioral examples, and more.

mcp

Start SpecSync as an MCP (Model Context Protocol) server over stdio. Enables AI agents like Claude Code, Cursor, and Windsurf to use SpecSync tools natively.

specsync mcp                            # start MCP server (stdio JSON-RPC)

Exposes tools: specsync_check, specsync_generate, specsync_coverage, specsync_score.

init

Create a default specsync.json in the current directory.

specsync init

watch

Live validation — re-runs on file changes with 500ms debounce. Ctrl+C to exit.

specsync watch

---

Flags

Flag	Description
--strict	Warnings become errors. Recommended for CI.
--require-coverage N	Fail if file coverage < N%.
--root <path>	Project root directory (default: cwd).
--provider <name>	Enable AI-powered generation and select provider: auto (auto-detect), anthropic, openai, or command. Without this flag, generate uses templates only.
--json	Structured JSON output, no color codes.

---

Exit Codes

Code	Meaning
0	All checks passed
1	Errors found, warnings with --strict, or coverage below threshold

---

JSON Output

Check

{
  "passed": false,
  "errors": ["auth.spec.md: phantom export `oldFunction` not found in source"],
  "warnings": ["auth.spec.md: undocumented export `newHelper`"],
  "specs_checked": 12
}

Coverage

{
  "file_coverage": 85.33,
  "files_covered": 23,
  "files_total": 27,
  "loc_coverage": 79.12,
  "loc_covered": 4200,
  "loc_total": 5308,
  "modules": [{ "name": "helpers", "has_spec": false }],
  "uncovered_files": [{ "file": "src/helpers/utils.ts", "loc": 340 }]
}