Auto-Claude CLI

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

Quick Reference

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

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

Command Options

spec_runner.py

run.py

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