Skip to content

CLI Reference

Every nspec command, generated from the argparse tree in src/nspec/cli.py. Required arguments are marked with *. Run nspec <command> --help for the authoritative flag list.

Commands

nspec audit

Run coverage audit with dead-code detection

  • Arguments: --coverage-json, --registry, --strict, --include, --exclude
  • Example: nspec audit

nspec config

Read config values

  • Arguments: key*
  • Example: nspec config <key>

nspec context-audit

Analyze CLAUDE.md for context budget and extraction candidates

  • Arguments: --file, --threshold
  • Example: nspec context-audit

nspec dashboard

Generate + stats combined

  • Arguments: --verbose-status, --epic
  • Example: nspec dashboard

nspec digest

Run the nightly activity digest

  • Arguments: --since, --dry-run
  • Example: nspec digest

nspec doctor

Run project health checks

  • Arguments: No arguments.
  • Example: nspec doctor

nspec generate

Generate NSPEC.md

  • Arguments: No arguments.
  • Example: nspec generate

nspec init

Initialize a new nspec project

  • Arguments: --ci (github|cloudbuild|gitlab|none), --force
  • Example: nspec init

nspec loop

—

  • Arguments: No arguments.
  • Example: nspec loop

nspec mcp

Run the MCP server

  • Arguments: No arguments.
  • Example: nspec mcp

nspec mcp-config

Print MCP configuration instructions

  • Arguments: No arguments.
  • Example: nspec mcp-config

nspec next

Show next unblocked spec to work on

  • Arguments: --epic, --json-output, --local
  • Example: nspec next

nspec ngtui

Launch next-gen TUI with accordion panels

  • Arguments: No arguments.
  • Example: nspec ngtui

nspec pr-gate

PR completeness gate

  • Arguments: --pr, --base
  • Example: nspec pr-gate

nspec repair-collisions

Detect and resolve cross-directory spec ID collisions (S909)

  • Arguments: --dry-run, --mode (rename-completed|rename-active|delete-completed), --force
  • Example: nspec repair-collisions

nspec stats

Show engineering metrics

  • Arguments: --format (text|json|yaml), --output
  • Example: nspec stats

nspec status-codes

Print FR and IMPL status codes reference

  • Arguments: No arguments.
  • Example: nspec status-codes

nspec statusline

Output compact status line for Claude Code

  • Arguments: --agent-id
  • Example: nspec statusline

nspec tui

Launch interactive TUI

  • Arguments: No arguments.
  • Example: nspec tui

nspec watchdog

Claude Code stall detector & auto-recovery

  • Arguments: --session, --stall-timeout, --mcp-stall-timeout, --poll-interval
  • Example: nspec watchdog

Command groups

nspec adr

Architecture Decision Records

  • Arguments: No arguments.
  • Example: nspec adr --help

nspec adr create

Create new ADR

  • Arguments: --title*
  • Example: nspec adr create --title <title>

nspec adr list

List all ADRs

  • Arguments: No arguments.
  • Example: nspec adr list

nspec dep

Dependency operations

  • Arguments: No arguments.
  • Example: nspec dep --help

nspec dep add

Add dependency

  • Arguments: --to, --dep
  • Example: nspec dep add --to <to> --dep <dep>

nspec dep clean

Remove dangling dependency references

  • Arguments: --dry-run
  • Example: nspec dep clean

nspec dep move

Move spec to epic

  • Arguments: --to, --dep
  • Example: nspec dep move --to <to> --dep <dep>

nspec dep remove

Remove dependency

  • Arguments: --to, --dep
  • Example: nspec dep remove --to <to> --dep <dep>

nspec hooks

Inspect and verify Claude Code hooks (policy-as-code)

  • Arguments: No arguments.
  • Example: nspec hooks --help

nspec hooks doctor

Verify policy hooks are installed and registered

  • Arguments: No arguments.
  • Example: nspec hooks doctor

nspec issue

GitHub issue integration (import issues as specs)

  • Arguments: No arguments.
  • Example: nspec issue --help

nspec issue import

Import a GitHub issue as an nspec spec

  • Arguments: --repo, --number*, --epic-id, --priority, --dry-run
  • Example: nspec issue import --number <number>

nspec issue list

List GitHub issues with mapped priorities

  • Arguments: --repo, --state (open|closed|all), --label
  • Example: nspec issue list

nspec issue status

Show issue pipeline status across lifecycle stages

  • Arguments: --repo
  • Example: nspec issue status

nspec linear

Linear integration (repo -> Linear sync)

  • Arguments: No arguments.
  • Example: nspec linear --help

nspec linear bootstrap

Print config snippet with Linear team/workflow state IDs

  • Arguments: No arguments.
  • Example: nspec linear bootstrap

nspec linear push

Push nspec state to linked Linear issues

  • Arguments: --since, --spec-id, --dry-run
  • Example: nspec linear push

nspec loop-retry

Loop retry tracking

  • Arguments: No arguments.
  • Example: nspec loop-retry --help

nspec loop-retry clear

Clear retry entry for a spec

  • Arguments: --id*
  • Example: nspec loop-retry clear --id <id>

nspec loop-retry count

Show retry count

  • Arguments: --id*
  • Example: nspec loop-retry count --id <id>

nspec loop-retry increment

Increment retry count

  • Arguments: --id*, --exit-reason
  • Example: nspec loop-retry increment --id <id>

nspec loop-retry list

List all retry entries

  • Arguments: No arguments.
  • Example: nspec loop-retry list

nspec loop-retry reset

Delete all retry data

  • Arguments: No arguments.
  • Example: nspec loop-retry reset

nspec queue

Agent assignment queue for parallel execution

  • Arguments: No arguments.
  • Example: nspec queue --help

nspec queue claim

Claim next spec

  • Arguments: --agent-id*
  • Example: nspec queue claim --agent-id <agent_id>

nspec queue drain

Show drain status

  • Arguments: No arguments.
  • Example: nspec queue drain

nspec queue init

Initialize queue from backlog

  • Arguments: --epic-id, --max-agents, --lease-ttl
  • Example: nspec queue init

nspec queue release

Release a claimed spec

  • Arguments: --agent-id, --spec-id, --reason, --completed
  • Example: nspec queue release --agent-id <agent_id> --spec-id <spec_id>

nspec queue status

Show queue state

  • Arguments: No arguments.
  • Example: nspec queue status

nspec review

Review packet workflow

  • Arguments: No arguments.
  • Example: nspec review --help

nspec review finalize

Archive + mark done + complete review spec

  • Arguments: --id*, --date
  • Example: nspec review finalize --id <id>

nspec session

Session management

  • Arguments: No arguments.
  • Example: nspec session --help

nspec session files

List modified files

  • Arguments: --since-commit
  • Example: nspec session files

nspec session handoff

Generate session handoff

  • Arguments: --id*
  • Example: nspec session handoff --id <id>

nspec session log

Append session note

  • Arguments: --id, --note
  • Example: nspec session log --id <id> --note <note>

nspec session start

Initialize session context

  • Arguments: --id*
  • Example: nspec session start --id <id>

nspec session sync

Sync spec state

  • Arguments: --id*, --force
  • Example: nspec session sync --id <id>

nspec skills

Manage nspec skills (slash commands)

  • Arguments: No arguments.
  • Example: nspec skills --help

nspec skills list

List available skills

  • Arguments: No arguments.
  • Example: nspec skills list

nspec skills sync

Install skills and sync symlinks to agent directories

  • Arguments: --force
  • Example: nspec skills sync

nspec spec

Spec CRUD operations

  • Arguments: No arguments.
  • Example: nspec spec --help

nspec spec complete

Archive spec as completed

  • Arguments: --id*
  • Example: nspec spec complete --id <id>

nspec spec context

LLM context for epic

  • Arguments: --id*
  • Example: nspec spec context --id <id>

nspec spec create

Create new FR+IMPL spec

  • Arguments: --title*, --priority, --epic, --type (spec|epic), --set-default
  • Example: nspec spec create --title <title>

nspec spec delete

Delete FR+IMPL spec

  • Arguments: --id*, --force
  • Example: nspec spec delete --id <id>

nspec spec deps

List dependencies

  • Arguments: --id*
  • Example: nspec spec deps --id <id>

nspec spec finalize

Show spec completion status

  • Arguments: --id*, --execute
  • Example: nspec spec finalize --id <id>

nspec spec move

Reassign a spec to a different epic

  • Arguments: spec_id, epic_id
  • Example: nspec spec move <spec_id> <epic_id>

nspec spec progress

Show task/AC progress

  • Arguments: --id, --all
  • Example: nspec spec progress

nspec spec reject

Archive spec as rejected

  • Arguments: --id*, --force
  • Example: nspec spec reject --id <id>

nspec spec rename

Retitle a spec/epic (ID-stable heading + slug rename via git mv)

  • Arguments: id, title
  • Example: nspec spec rename <id> <title>

nspec spec supersede

Archive spec as superseded

  • Arguments: --id*, --by
  • Example: nspec spec supersede --id <id>

nspec task

Task and property operations

  • Arguments: No arguments.
  • Example: nspec task --help

nspec task check

Mark task complete/obsolete

  • Arguments: --id, --task-id, --marker (x|~)
  • Example: nspec task check --id <id> --task-id <task_id>

nspec task criteria

Mark criterion complete/obsolete

  • Arguments: --id, --criteria-id, --marker (x|~)
  • Example: nspec task criteria --id <id> --criteria-id <criteria_id>

nspec task next-status

Advance to next status

  • Arguments: --id*
  • Example: nspec task next-status --id <id>

nspec task set-criteria

Add/edit/remove an AC line (never checks off)

  • Arguments: --id, --action (add|edit|remove), --label*, --section, --text
  • Example: nspec task set-criteria --id <id> --action <action> --label <label>

nspec task set-loe

Set LOE estimate

  • Arguments: --id, --loe
  • Example: nspec task set-loe --id <id> --loe <loe>

nspec task set-priority

Change priority

  • Arguments: --id, --priority
  • Example: nspec task set-priority --id <id> --priority <priority>

nspec task set-status

Set FR and IMPL status

  • Arguments: --id, --fr-status, --impl-status*, --force
  • Example: nspec task set-status --id <id> --fr-status <fr_status> --impl-status <impl_status>

nspec task set-task

Add/edit/remove an IMPL task line (no reorder)

  • Arguments: --id, --action (add|edit|remove), --phase, --task-id, --text, --file, --acknowledge-completed
  • Example: nspec task set-task --id <id> --action <action>

nspec tests

Manage test file associations

  • Arguments: No arguments.
  • Example: nspec tests --help

nspec tests add

Add test file entries

  • Arguments: files, --id
  • Example: nspec tests add --id <id> <files>

nspec tests remove

Remove test file entries

  • Arguments: files, --id
  • Example: nspec tests remove --id <id> <files>

nspec tracker

Tracker sync (audit back-comments, reconcile drift)

  • Arguments: No arguments.
  • Example: nspec tracker --help

nspec tracker audit

Check back-comments and status consistency for all linked specs

  • Arguments: --repo, --fix
  • Example: nspec tracker audit

nspec trail

List or show audit trail artifacts (decisions, inventories, handoffs)

  • Arguments: No arguments.
  • Example: nspec trail --help

nspec trail list

List audit artifacts

  • Arguments: kind (decision|inventory|handoff)
  • Example: nspec trail list

nspec trail show

Show an audit artifact by slug

  • Arguments: slug*
  • Example: nspec trail show <slug>

nspec validate

Run validation

  • Arguments: No arguments.
  • Example: nspec validate --help

nspec validate criteria

Validate acceptance criteria

  • Arguments: --id*, --strict
  • Example: nspec validate criteria --id <id>

nspec validate main

Validate main branch integrity

  • Arguments: No arguments.
  • Example: nspec validate main