CLI Commands

Complete reference for all autospec commands.

Table of contents

Global Flags
Workflow Commands
1. autospec run
2. autospec prep
Stage Commands
Status Commands
1. autospec status
2. autospec history
Utility Commands
Validation Commands
Exit Codes
Prerequisite Validation
See Also

Global Flags

All commands support these global flags:

Flag	Description
`--config`	Path to config file
`--specs-dir`	Directory for specifications
`--debug`	Enable debug output
`--verbose`	Enable verbose output

Workflow Commands

autospec run

Execute workflow stages (alias: autospec all).

autospec run [flags] ["description"] ["guidance"]

Stage Flags (select which stages to run):

Flag	Stage	Description
`-s`	specify	Generate spec.yaml from description
`-p`	plan	Generate plan.yaml from spec
`-t`	tasks	Generate tasks.yaml from plan
`-i`	implement	Execute tasks
`-a`	all	Run all stages (specify + plan + tasks + implement)

Other Flags:

Flag	Description
`--skip-preflight`	Skip dependency health checks
`--timeout <seconds>`	Command timeout (0=infinite)
`--max-retries <count>`	Maximum retry attempts (1-10)

Examples:

# Full workflow
autospec run -a "Add user authentication"

# Planning only (no implementation)
autospec run -spt "Add dark mode"

# Implementation only (after manual review)
autospec run -i

# With guidance
autospec run -a "Add caching" "Focus on Redis integration"

autospec prep

Planning only: specify, plan, tasks (no implementation).

autospec prep "description" [flags]

Equivalent to autospec run -spt.

Examples:

autospec prep "Add user profile page"
autospec prep "Implement caching" --max-retries 5

Stage Commands

autospec specify

Create feature specification from description.

autospec specify "description" ["guidance"] [flags]

Aliases: autospec spec, autospec s

Creates: specs/<branch>/spec.yaml

Examples:

autospec specify "Add real-time notifications"
autospec specify "Add rate limiting" "Focus on security"

autospec plan

Generate implementation plan from spec.yaml.

autospec plan ["guidance"] [flags]

Alias: autospec p

Requires: spec.yaml

Creates: plan.yaml

Examples:

autospec plan
autospec plan "Prioritize performance"

autospec tasks

Generate task breakdown from plan.yaml.

autospec tasks ["guidance"] [flags]

Alias: autospec t

Requires: plan.yaml

Creates: tasks.yaml

Examples:

autospec tasks
autospec tasks "Break into small steps"

autospec implement

Execute tasks from tasks.yaml.

autospec implement [spec-name] ["guidance"] [flags]

Aliases: autospec impl, autospec i

Requires: tasks.yaml

Execution Mode Flags:

Flag	Sessions	Description
(default)	1 per phase	Balanced cost/context
`--tasks`	1 per task	Maximum isolation
`--single-session`	1 total	All tasks in one session

Phase Selection:

Flag	Description
`--phase <N>`	Run only phase N
`--from-phase <N>`	Run phases N and onwards
`--from-task <ID>`	Resume from specific task

Examples:

# Default: one session per phase
autospec implement

# Run only phase 2
autospec implement --phase 2

# Resume from phase 3
autospec implement --from-phase 3

# Maximum context isolation
autospec implement --tasks

# Resume from specific task
autospec implement --from-task T005

# With guidance
autospec implement "Focus on tests first"

Status Commands

autospec status

Check current spec status and progress.

autospec status [spec-name] [flags]

Alias: autospec st

Flags:

Flag	Description
`-v, --verbose`	Show phase-by-phase breakdown

Output:

015-artifact-validation
  artifacts: [spec.yaml plan.yaml tasks.yaml]
  risks: 3 total (1 high, 2 medium)
  25/38 tasks completed (66%)
  7/10 task phases completed
  (1 in progress)

Examples:

autospec st
autospec st -v
autospec status 003-feature

autospec history

View command execution history.

autospec history [flags]

Flags:

Flag	Description
`-s, --spec <name>`	Filter by spec name
`-n, --limit <N>`	Show last N entries
`--status <value>`	Filter by status
`--clear`	Clear all history

Status Values: running, completed, failed, cancelled

Output:

TIMESTAMP            ID                         STATUS      COMMAND    SPEC      EXIT  DURATION
2024-01-15 10:30:00  brave_fox_20240115_103000  completed   specify    -         0     2m30s
2024-01-15 10:35:00  calm_river_20240115_103500 completed   plan       001-feat  0     1m15s

Examples:

autospec history
autospec history -n 10
autospec history --status failed
autospec history --spec 001-feature
autospec history --clear

Utility Commands

autospec doctor

Verify dependencies and configuration.

autospec doctor [flags]

Alias: autospec doc

Checks Claude CLI installation, authentication, and directory access.

autospec config

Manage configuration.

autospec config <subcommand> [flags]

Subcommands:

Command	Description
`show`	Display current configuration
`set <key> <value>`	Set configuration value
`get <key>`	Get configuration value
`init`	Initialize default configuration

Examples:

autospec config show
autospec config set max_retries 5
autospec config get timeout

autospec init

Initialize configuration files.

autospec init [flags]

Flags:

Flag	Description
`-p, --project`	Create project config (`.autospec/config.yml`)
`-f, --force`	Overwrite existing config

Examples:

autospec init
autospec init --project
autospec init --force

autospec version

Display version information.

autospec version

Alias: autospec v

Validation Commands

autospec artifact

Validate YAML artifacts against schemas.

autospec artifact <path>
autospec artifact <type> <path>

Types: spec, plan, tasks, analysis, checklist, constitution

Flags:

Flag	Description
`--schema`	Print expected schema
`--fix`	Auto-fix common issues

Examples:

# Type inferred from filename
autospec artifact specs/001-feature/spec.yaml
autospec artifact specs/001-feature/plan.yaml

# Explicit type (required for checklists)
autospec artifact checklist specs/001/checklists/ux.yaml

# Show schema
autospec artifact spec --schema

# Auto-fix
autospec artifact specs/001/plan.yaml --fix

autospec yaml check

Validate YAML syntax (no schema checking).

autospec yaml check <file>

Examples:

autospec yaml check specs/001-feature/spec.yaml

autospec update-task

Update task status in tasks.yaml.

autospec update-task <task-id> <status>

Status Values: Pending, InProgress, Completed, Blocked

Examples:

autospec update-task T001 InProgress
autospec update-task T001 Completed
autospec update-task T015 Blocked

Exit Codes

Code	Meaning	Action
0	Success	Continue workflow
1	Validation failed	Retry or inspect error
2	Retries exhausted	Reset state or fix issue
3	Invalid arguments	Check command syntax
4	Missing dependencies	Install required tools
5	Timeout	Increase timeout

Bash Example:

autospec prep "feature"
if [ $? -eq 0 ]; then
    echo "Success"
elif [ $? -eq 2 ]; then
    echo "Retries exhausted"
    rm ~/.autospec/state/retry.json
fi

Prerequisite Validation

Commands validate required artifacts before execution:

Command	Required
`specify`	(none)
`plan`	spec.yaml
`tasks`	plan.yaml
`implement`	tasks.yaml
`clarify`	spec.yaml
`analyze`	spec.yaml, plan.yaml, tasks.yaml

Missing prerequisite error:

Error: spec.yaml not found.

Run 'autospec specify' first to create this file.

All stage commands also require a project constitution (.autospec/memory/constitution.yaml). Run autospec constitution to create one.

CLI Commands

Global Flags

Workflow Commands

autospec run

autospec prep

Stage Commands

autospec specify

autospec plan

autospec tasks

autospec implement

Status Commands

autospec status

autospec history

Utility Commands

autospec doctor

autospec config

autospec init

autospec version

Validation Commands

autospec artifact

autospec yaml check

autospec update-task

Exit Codes

Prerequisite Validation

See Also