CLI Reference

Project Setup

Command	Description
nspec init	Scaffold nspec project (auto-detects stack)
nspec init --ci github	Scaffold with GitHub Actions CI
nspec init --ci gitlab	Scaffold with GitLab CI
nspec init --force	Overwrite existing files
nspec mcp-config	Generate MCP server config for your stack
nspec doctor	Run project health checks (config, dirs, validation, MCP)

Validation & Output

Command	Description
nspec validate	Run all 6 validation layers
nspec validate criteria --id ID	Validate acceptance criteria for a spec
nspec generate	Generate NSPEC.md and NSPEC_COMPLETED.md
nspec dashboard	Generate + show engineering metrics
nspec stats	Velocity, quality, and DORA metrics
nspec statusline	Compact one-line status for editor/agent integration
nspec status-codes	Print FR and IMPL status codes reference table

Terminal UI

Command	Description
nspec tui	Open interactive terminal UI
nspec ngtui	Launch next-gen TUI with collapsible epic accordion panels

Spec Management (nspec spec)

Command	Description
nspec spec create --title "T" [--priority P1] [--epic ID]	Create FR+IMPL pair
nspec spec create --template quick	Create with minimal ceremony
nspec spec delete --id ID [--force]	Delete FR+IMPL files
nspec spec complete --id ID	Archive to completed/done
nspec spec supersede --id ID	Archive to completed/superseded
nspec spec reject --id ID	Archive to completed/rejected
nspec spec finalize --id ID	Show spec completion status
nspec spec progress [--id ID]	Task and acceptance criteria progress
nspec spec deps --id ID	List direct dependencies
nspec spec context --id ID	LLM-friendly YAML context for an epic

Dependencies (nspec dep)

Command	Description
nspec dep add --to ID --dep DEP	Add dependency
nspec dep remove --to ID --dep DEP	Remove dependency
nspec dep move --to EPIC --dep ID	Move spec to epic

Tasks & Properties (nspec task)

Command	Description
nspec task check --id ID --task-id 1.1	Mark task complete
nspec task criteria --id ID --criteria-id AC-F1	Mark criterion complete
nspec task set-priority --id ID --priority P0	Change spec priority
nspec task set-loe --id ID --loe "3d"	Set level of effort
nspec task next-status --id ID	Advance IMPL to next status
nspec task set-status --id ID --fr-status N --impl-status N	Set status codes directly

Session Management (nspec session)

Command	Description
nspec session start --id ID	Initialize work session
nspec session log --id ID --note "text"	Append execution notes
nspec session handoff --id ID	Generate session handoff summary
nspec session sync --id ID [--force]	Sync spec state across files
nspec session files [--since-commit REF]	List modified files

Review (nspec review)

Command	Description
nspec review	Run review workflow for the active spec

Multi-Agent Queue (nspec queue)

Command	Description
nspec queue init --epic ID [--max-agents N]	Initialize queue from eligible specs
nspec queue claim --agent-id NAME	Atomically claim next unclaimed spec
nspec queue release --agent-id NAME --spec-id ID [--completed]	Release spec back to queue or mark done
nspec queue status	Show agents, queued specs, completed count
nspec queue drain	Release all claims and clear queue state

GitHub Issues (nspec issue)

Command	Description
nspec issue import --issue NUMBER [--repo OWNER/REPO]	Import a GitHub issue as an nspec spec
nspec issue list [--repo OWNER/REPO]	List open issues from a repository
nspec issue status	Show sync status between specs and issues

Skills Management (nspec skills)

Command	Description
nspec skills list	List installed skills with source info
nspec skills sync	Re-sync skills from sources (after nspec upgrade)

Autonomous Loop (nspec loop)

Command	Description
nspec loop	Run the loop orchestrator for autonomous spec processing
nspec loop-retry increment --id ID	Increment retry count for a spec
nspec loop-retry count --id ID	Get current retry count
nspec loop-retry clear --id ID	Clear retry count
nspec loop-retry list	List all retry counts
nspec loop-retry reset	Reset all retry counts

Watchdog (nspec watchdog)

Command	Description
nspec watchdog --session NAME	Monitor a tmux session for Claude Code API stalls
nspec watchdog --stall-timeout N	Seconds before declaring token stall (default: 180)
nspec watchdog --poll-interval N	Seconds between polls (default: 15)

Audit & Analysis

Command	Description
nspec audit	Run coverage audit with dead-code detection
nspec audit --strict	Fail on uncovered candidates
nspec trail list	List audit trail artifacts
nspec trail show ARTIFACT	Show a specific audit artifact
nspec context-audit	Analyze CLAUDE.md for context budget and extraction candidates
nspec context-audit --threshold N	Set threshold for extraction recommendations

Tracker Sync (nspec tracker)

Command	Description
nspec tracker audit	Audit and reconcile bidirectional links between specs and GitHub issues

Linear Integration (nspec linear)

Command	Description
nspec linear push	Sync nspec spec state to Linear issues
nspec linear bootstrap	Bootstrap Linear project from nspec backlog

Configuration (nspec config)

Command	Description
nspec config KEY	Read configuration value by dotted key path (e.g., nspec config review.agent)

Architecture Decision Records (nspec adr)

Command	Description
nspec adr create --title "Decision"	Create ADR (FR-900–999 range)
nspec adr list	List all ADRs with status

Collision Repair

Command	Description
nspec repair-collisions	Detect and resolve spec ID collisions after branch merges
nspec repair-collisions --dry-run	Preview collisions without modifying files

MCP Server (nspec mcp)

Command	Description
nspec mcp	Run MCP server (stdio transport, default)
nspec mcp --sse	Run MCP server with SSE transport
nspec mcp --http	Run MCP server with HTTP transport

Makefile Integration

nspec init generates nspec.mk — include it in your Makefile:

include nspec.mk

Provides targets: nspec.validate, nspec.generate, nspec.dashboard, nspec.tui, nspec.stats, nspec.check.

The NSPEC variable is auto-configured for your stack (e.g., poetry run nspec, uv run nspec).

CI/CD Integration

nspec init --ci github      # .github/workflows/nspec.yml
nspec init --ci gitlab       # .gitlab-ci.yml

All CI templates validate specifications and generate NSPEC.md on every push/PR.