---
title: CLI Reference
layout: default
nav_order: 3
---
# CLI Reference
{: .no_toc }
<details open markdown="block">
<summary>Table of contents</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
---
## Usage
```
specsync [command] [flags]
```
Default command is `check`.
---
## Commands
### `check`
Validate all specs against source code.
```bash
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.
```bash
specsync coverage
specsync coverage --json
```
### `generate`
Scaffold spec files for modules that don't have one. Uses `specs/_template.spec.md` if present.
```bash
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](configuration) for `aiCommand` and `aiTimeout`.
### `score`
Quality-score your spec files on a 0–100 scale with per-spec improvement suggestions.
```bash
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.
```bash
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.
```bash
specsync init
```
### `watch`
Live validation — re-runs on file changes with 500ms debounce. `Ctrl+C` to exit.
```bash
specsync watch
```
---
## Flags
| `--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
| `0` | All checks passed |
| `1` | Errors found, warnings with `--strict`, or coverage below threshold |
---
## JSON Output
### Check
```json
{
"passed": false,
"errors": ["auth.spec.md: phantom export `oldFunction` not found in source"],
"warnings": ["auth.spec.md: undocumented export `newHelper`"],
"specs_checked": 12
}
```
### Coverage
```json
{
"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 }]
}
```