Skip to content
Spectr

CLI Commands

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

Essential Commands

Section titled “Essential Commands”

List Changes and Specs

Section titled “List Changes and Specs”

List all active changes and specifications:

Terminal window
spectr list
```text


List specifications with detailed information:


```bash
spectr list --specs
spectr spec list --long
```text


**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:


```bash
spectr view <change-id>
spectr view <spec-id> --type spec
```text


**Examples:**


```bash
# 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
```text


**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. Validation is always comprehensive (strict
mode).


```bash
spectr validate <change-id>
```text


**Examples:**


```bash
# Validate single change
spectr validate add-two-factor-auth


# Bulk validation (interactive)
spectr validate


# Validate all specs
spectr validate --specs
```text


**Options:**


- `--specs` - Validate specs instead of changes
- `--no-interactive` - Disable prompts


### Archive a Change


Move a completed change to archive and merge specs:


```bash
spectr archive <change-id> --yes
```text


**Examples:**


```bash
# 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
```text


**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:


```bash
spectr init [path]
```text


**Examples:**


```bash
# Initialize in current directory
spectr init


# Initialize in specific directory
spectr init ./docs
```text


This also updates the instruction markdown files in the project.


## Global Options


Most commands support these global options:


```bash
spectr [command] [options]
```text


- `--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:


```bash
# Interactive spec selection
spectr view


# Interactive validation
spectr validate


# Interactive archiving
spectr archive
```text


## Output Formats


### Text Output (Default)


Human-readable text format:


```bash
spectr list
```text


Output:


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


### JSON Output


Machine-readable JSON format:


```bash
spectr list --json
```text


Output:


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


## Common Workflows


### Create and Validate a Change


```bash
# 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


# 4. Fix any issues shown in validation


# 5. Validate again
spectr validate add-feature
```text


### Implement and Archive


```bash
# 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


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


# 6. Verify specs were updated
spectr validate
```text


### Explore Project State


```bash
# 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
```text


## Troubleshooting


### Command not found


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


```bash
# Check installation
which spectr


# Install if needed (see Installation guide)
```text


### Ambiguous item


If you get "ambiguous item" error, specify the type:


```bash
# Error: Could be change or spec
spectr view auth


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


### Permission denied


If you get permission errors when creating files:


```bash
# Check directory permissions
ls -la spectr/


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


## Tips and Tricks


### Piping JSON


Use JSON output with `jq` for filtering:


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


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


### Quick Validation Loop


Validate multiple times while editing:


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


### List Specs by Capability


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


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


## Further Reading


- [Creating Changes](/guides/creating-changes)
- [Archiving Workflow](/guides/archiving-workflow)
- [Configuration](/reference/configuration)