Auto-Claude CLI

Complete command-line interface reference for Auto-Claude autonomous coding framework.

Quick Reference

Command	Purpose
python spec_runner.py --interactive	Create spec interactively
python spec_runner.py --task "..."	Create spec from description
python run.py --spec 001	Run autonomous build
python run.py --list	List all specs
python run.py --spec 001 --review	Review changes
python run.py --spec 001 --merge	Merge to project

Setup

All CLI commands run from apps/backend/:

cd Auto-Claude/apps/backend

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

Core Commands

Creating Specs

# Interactive spec creation (recommended for complex tasks)
python spec_runner.py --interactive

# Quick spec from task description
python spec_runner.py --task "Add user authentication with OAuth"

# Force complexity level
python spec_runner.py --task "Fix button color" --complexity simple
python spec_runner.py --task "Add dark mode" --complexity standard
python spec_runner.py --task "Implement payment system" --complexity complex

# Continue an interrupted spec creation
python spec_runner.py --continue 001-feature-name

Complexity Tiers

Tier	Phases	When Used
SIMPLE	3	1-2 files, single service, no integrations (UI fixes, text changes)
STANDARD	6-7	3-10 files, 1-2 services, minimal integrations (features, bug fixes)
COMPLEX	8	10+ files, multiple services, external integrations

Running Builds

# List all specs and their status
python run.py --list

# Run a specific spec (by number or full name)
python run.py --spec 001
python run.py --spec 001-feature-name

# Limit iterations for testing
python run.py --spec 001 --max-iterations 5

# Skip automatic QA
python run.py --spec 001 --skip-qa

QA Validation

# Run QA validation manually
python run.py --spec 001 --qa

# Check QA status
python run.py --spec 001 --qa-status

The QA loop:

1. QA Reviewer checks acceptance criteria
2. If issues found → creates QA_FIX_REQUEST.md
3. QA Fixer applies fixes
4. Loop repeats until approved (up to 50 iterations)

Workspace Management

# Test the feature in isolated workspace
cd .worktrees/auto-claude/{spec-name}/
npm run dev  # or your project's run command

# Return to backend for management commands
cd apps/backend

# See what was changed
python run.py --spec 001 --review

# Merge changes into your project
python run.py --spec 001 --merge

# Discard if you don't like it
python run.py --spec 001 --discard

Spec Validation

# Validate a spec against all checkpoints
python validate_spec.py --spec-dir specs/001-feature --checkpoint all

# Validate specific checkpoint
python validate_spec.py --spec-dir specs/001-feature --checkpoint requirements

Interactive Controls

During Build

# Pause and add instructions (press once)
Ctrl+C

# Exit immediately (press twice)
Ctrl+C Ctrl+C

File-Based Control

# Pause after current session
touch specs/001-name/PAUSE

# Add human instructions
echo "Focus on fixing the login bug first" > specs/001-name/HUMAN_INPUT.md

# Remove pause to continue
rm specs/001-name/PAUSE

Environment Variables

Variable	Required	Default	Description
CLAUDE_CODE_OAUTH_TOKEN	Yes	-	OAuth token from claude setup-token
AUTO_BUILD_MODEL	No	claude-opus-4-5-20251101	Model override
DEFAULT_BRANCH	No	auto-detect	Base branch for worktrees
DEBUG	No	false	Enable debug logging
DEBUG_LEVEL	No	1	Debug verbosity (1-3)
GRAPHITI_ENABLED	No	true	Enable memory system
LINEAR_API_KEY	No	-	Linear integration

Command Options

spec_runner.py

Option	Description
--interactive	Interactive spec creation mode
--task "..."	Create spec from task description
--complexity LEVEL	Force complexity (simple/standard/complex)
--continue SPEC	Continue interrupted spec creation

run.py

Option	Description
--spec SPEC	Run or manage specific spec
--list	List all specs with status
--review	Show changes in worktree
--merge	Merge changes to project
--discard	Delete build (with confirmation)
--qa	Run QA validation
--qa-status	Check QA status
--skip-qa	Skip automatic QA
--max-iterations N	Limit build iterations

Workflow Examples

Complete Feature Development

# 1. Create spec
python spec_runner.py --task "Add user profile page with avatar upload"

# 2. Run build (finds latest spec automatically)
python run.py --spec 001

# 3. Review changes in isolated workspace
python run.py --spec 001 --review

# 4. Test in worktree
cd .worktrees/auto-claude/001-user-profile/
npm run dev

# 5. Merge to project
cd ../../../apps/backend
python run.py --spec 001 --merge

Quick Bug Fix

# Simple fix with minimal phases
python spec_runner.py --task "Fix login button alignment" --complexity simple

# Run and merge
python run.py --spec 002
python run.py --spec 002 --merge

Batch Processing

# Create multiple specs
python spec_runner.py --task "Add search functionality"
python spec_runner.py --task "Add filters to search"
python spec_runner.py --task "Add search history"

# Run them in sequence
python run.py --spec 001
python run.py --spec 002
python run.py --spec 003

Spec Directory Structure

Each spec creates a directory in .auto-claude/specs/XXX-name/:

001-feature-name/
├── spec.md                    # Feature specification
├── requirements.json          # Structured requirements
├── context.json               # Discovered codebase context
├── implementation_plan.json   # Subtask-based plan
├── qa_report.md              # QA validation results
├── QA_FIX_REQUEST.md         # Issues to fix (if rejected)
├── PAUSE                      # Pause file (if present)
└── HUMAN_INPUT.md            # Human instructions

Tips for Effective Use

Writing Good Task Descriptions

# Good: Specific and actionable
python spec_runner.py --task "Add user authentication with Google OAuth, including login button on header and protected routes for /dashboard/*"

# Bad: Vague
python spec_runner.py --task "Add login"

Choosing Complexity

• Simple: Single file changes, UI tweaks, text updates
• Standard: Most features, bug fixes, component additions
• Complex: Multi-service changes, external integrations, architectural changes

Debugging Failed Builds

# Enable verbose logging
DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001

# Check spec status
python run.py --list

# Review QA report
cat .auto-claude/specs/001-feature/qa_report.md

Related Skills

• auto-claude-spec: Detailed spec creation workflow
• auto-claude-build: Build process deep dive
• auto-claude-workspace: Workspace management
• auto-claude-troubleshooting: Debugging issues