CLI Commands

This page documents all available Spectr CLI commands and their options.

Essential Commands

List Changes and Specs

List all active changes and specifications:

spectr list

List specifications with detailed information:

spectr list --specs
spectr spec list --long

Options:

• --specs - Show specifications instead of changes
• --long - Show detailed information
• --json - Machine-readable JSON output

View Details

Display details about a specific change or spec:

spectr view <change-id>
spectr view <spec-id> --type spec

Examples:

# View change details
spectr view add-two-factor-auth

# View spec details
spectr view auth --type spec

# JSON output with delta details
spectr view add-two-factor-auth --json --deltas-only

Options:

• --type change|spec - Specify what to view (required if ambiguous)
• --json - Machine-readable JSON output
• --deltas-only - Show only spec deltas

Validate Changes and Specs

Validate a change or specification:

spectr validate <change-id>
spectr validate --strict

Examples:

# Validate single change
spectr validate add-two-factor-auth --strict

# Bulk validation (interactive)
spectr validate

# Validate all specs
spectr validate --specs

Options:

• --strict - Comprehensive validation with all checks
• --specs - Validate specs instead of changes
• --no-interactive - Disable prompts

Archive a Change

Move a completed change to archive and merge specs:

spectr archive <change-id> --yes

Examples:

# Interactive archiving
spectr archive add-two-factor-auth

# Non-interactive (use --yes flag)
spectr archive add-two-factor-auth --yes

# Archive without updating specs
spectr archive add-two-factor-auth --skip-specs --yes

Options:

• --yes, -y - Skip confirmation prompts
• --skip-specs - Archive without merging specs
• --no-interactive - Disable all prompts

Project Management

Initialize Spectr

Initialize a new Spectr project:

spectr init [path]

Examples:

# Initialize in current directory
spectr init

# Initialize in specific directory
spectr init ./docs

This also updates the instruction markdown files in the project.

Global Options

Most commands support these global options:

spectr [command] [options]

• --help - Show command help
• --version - Show Spectr version
• --json - Output as JSON (where supported)
• --no-interactive - Disable interactive prompts

Interactive Mode

Some commands support interactive mode:

# Interactive spec selection
spectr view

# Interactive validation
spectr validate

# Interactive archiving
spectr archive

Output Formats

Text Output (Default)

Human-readable text format:

spectr list

Output:

Active Changes:
├─ add-two-factor-auth (created 2025-01-15)
│  ├─ status: pending
│  └─ affected: auth, notifications
└─ update-api-versioning (created 2025-01-10)

JSON Output

Machine-readable JSON format:

spectr list --json

Output:

{
  "changes": [
    {
      "id": "add-two-factor-auth",
      "created": "2025-01-15T10:30:00Z",
      "status": "pending",
      "affectedSpecs": ["auth", "notifications"]
    }
  ]
}

Common Workflows

Create and Validate a Change

# 1. Create change directory and files
mkdir -p spectr/changes/add-feature/specs/auth

# 2. Write proposal.md, tasks.md, and spec.md files

# 3. Validate the change
spectr validate add-feature --strict

# 4. Fix any issues shown in validation

# 5. Validate again
spectr validate add-feature --strict

Implement and Archive

# 1. Check change details
spectr view add-feature

# 2. Implement according to tasks.md

# 3. Mark all tasks complete in tasks.md

# 4. Validate before archiving
spectr validate add-feature --strict

# 5. Archive the change
spectr archive add-feature --yes

# 6. Verify specs were updated
spectr validate --strict

Explore Project State

# 1. List all active changes
spectr list

# 2. List all specs
spectr list --specs

# 3. View details of a change
spectr view add-feature

# 4. View details of a spec
spectr view auth --type spec

# 5. Validate everything
spectr validate --strict

Troubleshooting

Command not found

If you get “command not found”, ensure Spectr is installed:

# Check installation
which spectr

# Install if needed (see Installation guide)

Ambiguous item

If you get “ambiguous item” error, specify the type:

# Error: Could be change or spec
spectr view auth

# Solution: Specify type
spectr view auth --type spec

Permission denied

If you get permission errors when creating files:

# Check directory permissions
ls -la spectr/

# Ensure you have write permission
chmod -R u+w spectr/

Tips and Tricks

Piping JSON

Use JSON output with jq for filtering:

# Get all change IDs
spectr list --json | jq '.changes[].id'

# Get specific change details
spectr view add-feature --json | jq '.proposal'

Quick Validation Loop

Validate multiple times while editing:

# Watch validation results
while true; do
  clear
  spectr validate add-feature --strict
  sleep 2
done

List Specs by Capability

# Show all specs with details
spectr spec list --long

# Find specs matching a pattern
spectr spec list --json | jq '.specs[] | select(.id | contains("auth"))'

Further Reading

• Creating Changes
• Archiving Workflow
• Configuration