CLI Reference
CLI Reference
Complete reference for all betterspec CLI commands.
CLI Reference
The betterspec CLI is a pure data tool. It reads and writes specs, manages knowledge, and runs drift analysis — no AI required. Your AI coding platform (OpenCode, Claude Code, Gemini CLI, Codex, Cursor) calls betterspec and acts on the results.
Installation
bun i -g @betterspec/cliAll commands support -C, --cwd <path> to set the working directory.
Commands
Spec Lifecycle
| Command | Description |
|---|---|
init | Initialize betterspec in a project |
propose | Create a new change proposal |
show | View all spec files for a change |
verify | Check spec completeness (structural) |
archive | Archive a completed change and capture knowledge |
Visibility & Navigation
| Command | Description |
|---|---|
status | Show project status dashboard |
list | List all changes with filters |
capabilities | List registered capabilities |
diff | Show drift score and spec gaps |
impact | Show what references a file or path |
Configuration & Maintenance
| Command | Description |
|---|---|
config | Get or set configuration values |
doctor | Health check and diagnostics |
sync | Sync with global spec repository |
serve | Start the betterspec MCP server |
Global Options
-C, --cwd <path> Set working directory
-V, --version Output version number
-h, --help Display helpbetterspec is not an AI tool
betterspec does not call AI. There are no AI-powered commands in the CLI. Instead, your AI coding platform reads specs from the filesystem or via the MCP server, reasons about them, and calls betterspec CLI commands to act on the results.
This keeps betterspec fast, deterministic, and provider-agnostic. The intelligence lives in your AI tool — betterspec manages the data layer.
AI platform (OpenCode / Claude Code / Gemini / Codex)
│
├─ reads betterspec/changes/*/specs/
├─ reads betterspec/knowledge/
├─ calls betterspec propose / verify / archive / diff
└─ calls @betterspec/mcp tools