CLI Reference

The AnchorSpec CLI (anchorspec) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like /ansx:propose) documented in Commands.

Summary

Human vs Agent Commands

Most CLI commands are designed for human use in a terminal. Some commands also support agent/script use via JSON output.

Human-Only Commands

These commands are interactive and designed for terminal use:

Agent-Compatible Commands

These commands support --json output for programmatic use by AI agents and scripts:

Global Options

These options work with all commands:

Setup Commands

anchorspec init

Initialize AnchorSpec in your project. Creates the folder structure and configures AI tool integrations.

Default behavior uses global config defaults: profile core, delivery both, workflows propose, explore, apply, archive.

anchorspec init [path] [options]

Arguments:

Options:

--profile custom uses whatever workflows are currently selected in global config (anchorspec config profile).

Supported tool IDs (--tools): amazon-q, antigravity, auggie, claude, cline, codex, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, kiro, opencode, pi, qoder, qwen, roocode, trae, windsurf

Examples:

# Interactive initialization
anchorspec init

# Initialize in a specific directory
anchorspec init ./my-project

# Non-interactive: configure for Claude and Cursor
anchorspec init --tools claude,cursor

# Configure for all supported tools
anchorspec init --tools all

# Override profile for this run
anchorspec init --profile core

# Skip prompts and auto-cleanup legacy files
anchorspec init --force

What it creates:

anchorspec/
├── specs/              # Your specifications (source of truth)
├── changes/            # Proposed changes
└── config.yaml         # Project configuration

.claude/skills/         # Claude Code skills (if claude selected)
.cursor/skills/         # Cursor skills (if cursor selected)
.cursor/commands/       # Cursor ANSX commands (if delivery includes commands)
... (other tool configs)

anchorspec update

Update AnchorSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files using your current global profile, selected workflows, and delivery mode.

anchorspec update [path] [options]

Arguments:

Options:

Example:

# Update instruction files after npm upgrade
npm update anchorspec
anchorspec update

Browsing Commands

anchorspec list

List changes or specs in your project.

anchorspec list [options]

Options:

Examples:

# List all active changes
anchorspec list

# List all specs
anchorspec list --specs

# JSON output for scripts
anchorspec list --json

Output (text):

Active changes:
  add-dark-mode     UI theme switching support
  fix-login-bug     Session timeout handling

anchorspec view

Display an interactive dashboard for exploring specs and changes.

anchorspec view

Opens a terminal-based interface for navigating your project’s specifications and changes.

anchorspec show

Display details of a change or spec.

anchorspec show [item-name] [options]

Arguments:

Options:

Change-specific options:

Spec-specific options:

Examples:

# Interactive selection
anchorspec show

# Show a specific change
anchorspec show add-dark-mode

# Show a specific spec
anchorspec show auth --type spec

# JSON output for parsing
anchorspec show add-dark-mode --json

Validation Commands

anchorspec validate

Validate changes and specs for structural issues.

anchorspec validate [item-name] [options]

Arguments:

Options:

Examples:

# Interactive validation
anchorspec validate

# Validate a specific change
anchorspec validate add-dark-mode

# Validate all changes
anchorspec validate --changes

# Validate everything with JSON output (for CI/scripts)
anchorspec validate --all --json

# Strict validation with increased parallelism
anchorspec validate --all --strict --concurrency 12

Output (text):

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

1 warning found

Output (JSON):

{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

Lifecycle Commands

anchorspec archive

Archive a completed change and merge delta specs into main specs.

anchorspec archive [change-name] [options]

Arguments:

Options:

Examples:

# Interactive archive
anchorspec archive

# Archive specific change
anchorspec archive add-dark-mode

# Archive without prompts (CI/scripts)
anchorspec archive add-dark-mode --yes

# Archive a tooling change that doesn't affect specs
anchorspec archive update-ci-config --skip-specs

What it does:

1. Validates the change (unless --no-validate)
2. Prompts for confirmation (unless --yes)
3. Merges delta specs into anchorspec/specs/
4. Moves change folder to anchorspec/changes/archive/YYYY-MM-DD-<name>/

Workflow Commands

These commands support the artifact-driven ANSX workflow. They’re useful for both humans checking progress and agents determining next steps.

anchorspec status

Display artifact completion status for a change.

anchorspec status [options]

Options:

Examples:

# Interactive status check
anchorspec status

# Status for specific change
anchorspec status --change add-dark-mode

# JSON for agent use
anchorspec status --change add-dark-mode --json

Output (text):

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[ ] design
[x] specs
[-] tasks (blocked by: design)

Output (JSON):

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done"},
    {"id": "design", "outputPath": "design.md", "status": "ready"},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]}
  ]
}

anchorspec instructions

Get enriched instructions for creating an artifact or applying tasks. Used by AI agents to understand what to create next.

anchorspec instructions [artifact] [options]

Arguments:

Options:

Special case: Use apply as the artifact to get task implementation instructions.

Examples:

# Get instructions for next artifact
anchorspec instructions --change add-dark-mode

# Get specific artifact instructions
anchorspec instructions design --change add-dark-mode

# Get apply/implementation instructions
anchorspec instructions apply --change add-dark-mode

# JSON for agent consumption
anchorspec instructions design --change add-dark-mode --json

Output includes:

• Template content for the artifact
• Project context from config
• Content from dependency artifacts
• Per-artifact rules from config

anchorspec templates

Show resolved template paths for all artifacts in a schema.

anchorspec templates [options]

Options:

Examples:

# Show template paths for default schema
anchorspec templates

# Show templates for custom schema
anchorspec templates --schema my-workflow

# JSON for programmatic use
anchorspec templates --json

Output (text):

Schema: spec-driven

Templates:
  proposal  → ~/.anchorspec/schemas/spec-driven/templates/proposal.md
  specs     → ~/.anchorspec/schemas/spec-driven/templates/specs.md
  design    → ~/.anchorspec/schemas/spec-driven/templates/design.md
  tasks     → ~/.anchorspec/schemas/spec-driven/templates/tasks.md

anchorspec schemas

List available workflow schemas with their descriptions and artifact flows.

anchorspec schemas [options]

Options:

Example:

anchorspec schemas

Output:

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Custom workflow for this project
    Flow: research → proposal → tasks

Schema Commands

Commands for creating and managing custom workflow schemas.

anchorspec schema init

Create a new project-local schema.

anchorspec schema init <name> [options]

Arguments:

Options:

Examples:

# Interactive schema creation
anchorspec schema init research-first

# Non-interactive with specific artifacts
anchorspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

What it creates:

anchorspec/schemas/<name>/
├── schema.yaml           # Schema definition
└── templates/
    ├── proposal.md       # Template for each artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

anchorspec schema fork

Copy an existing schema to your project for customization.

anchorspec schema fork <source> [name] [options]

Arguments:

Options:

Example:

# Fork the built-in spec-driven schema
anchorspec schema fork spec-driven my-workflow

anchorspec schema validate

Validate a schema’s structure and templates.

anchorspec schema validate [name] [options]

Arguments:

Options:

Example:

# Validate a specific schema
anchorspec schema validate my-workflow

# Validate all schemas
anchorspec schema validate

anchorspec schema which

Show where a schema resolves from (useful for debugging precedence).

anchorspec schema which [name] [options]

Arguments:

Options:

Example:

# Check where a schema comes from
anchorspec schema which spec-driven

Output:

spec-driven resolves from: package
  Source: /usr/local/lib/node_modules/anchorspec/schemas/spec-driven

Schema precedence:

1. Project: anchorspec/schemas/<name>/
2. User: ~/.local/share/anchorspec/schemas/<name>/
3. Package: Built-in schemas

Configuration Commands

anchorspec config

View and modify global AnchorSpec configuration.

anchorspec config <subcommand> [options]

Subcommands:

Examples:

# Show config file path
anchorspec config path

# List all settings
anchorspec config list

# Get a specific value
anchorspec config get telemetry.enabled

# Set a value
anchorspec config set telemetry.enabled false

# Set a string value explicitly
anchorspec config set user.name "My Name" --string

# Remove a custom setting
anchorspec config unset user.name

# Reset all configuration
anchorspec config reset --all --yes

# Edit config in your editor
anchorspec config edit

# Configure profile with action-based wizard
anchorspec config profile

# Fast preset: switch workflows to core (keeps delivery mode)
anchorspec config profile core

anchorspec config profile starts with a current-state summary, then lets you choose:

• Change delivery + workflows
• Change delivery only
• Change workflows only
• Keep current settings (exit)

If you keep current settings, no changes are written and no update prompt is shown. If there are no config changes but the current project files are out of sync with your global profile/delivery, AnchorSpec will show a warning and suggest running anchorspec update. Pressing Ctrl+C also cancels the flow cleanly (no stack trace) and exits with code 130. In the workflow checklist, [x] means the workflow is selected in global config. To apply those selections to project files, run anchorspec update (or choose Apply changes to this project now? when prompted inside a project).

Interactive examples:

# Delivery-only update
anchorspec config profile
# choose: Change delivery only
# choose delivery: Skills only

# Workflows-only update
anchorspec config profile
# choose: Change workflows only
# toggle workflows in the checklist, then confirm

Utility Commands

anchorspec feedback

Submit feedback about AnchorSpec. Creates a GitHub issue.

anchorspec feedback <message> [options]

Arguments:

Options:

Requirements: GitHub CLI (gh) must be installed and authenticated.

Example:

anchorspec feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

anchorspec completion

Manage shell completions for the AnchorSpec CLI.

anchorspec completion <subcommand> [shell]

Subcommands:

Supported shells: bash, zsh, fish, powershell

Examples:

# Install completions (auto-detects shell)
anchorspec completion install

# Install for specific shell
anchorspec completion install zsh

# Generate script for manual installation
anchorspec completion generate bash > ~/.bash_completion.d/anchorspec

# Uninstall
anchorspec completion uninstall

Exit Codes

Environment Variables

Related Documentation

• Commands - AI slash commands (/ansx:propose, /ansx:apply, etc.)
• Workflows - Common patterns and when to use each command
• Customization - Create custom schemas and templates
• Getting Started - First-time setup guide