CLI Reference

Complete documentation for all YOLO Developer command-line interface commands.

Overview
1. Basic Usage
2. Interactive Mode
3. Global Options
Command Summary
yolo chat
1. Synopsis
2. Examples
yolo integrate
1. Synopsis
2. Options
3. Examples
yolo init
1. Synopsis
2. Options
3. Git Repository Features
4. Examples
5. Files Created
yolo seed
1. Synopsis
2. Arguments
3. Options
4. Examples
5. Input Formats
yolo run
1. Synopsis
2. Options
3. Examples
4. Agent Execution Order
yolo status
1. Synopsis
2. Options
3. Examples
yolo logs
1. Synopsis
2. Options
3. Examples
yolo config
1. Synopsis
2. Commands
3. Examples
yolo tools
1. Synopsis
2. Commands
3. Options
4. Examples
5. Configuration
yolo tune
1. Synopsis
2. Options
3. Examples
yolo mcp
1. Synopsis
2. Options
3. Examples
yolo scan
1. Synopsis
2. Options
3. Examples
yolo git
yolo pr
yolo issue
yolo release
yolo workflow
yolo import
yolo gather
yolo web
Exit Codes
Exit Codes
Environment Variables
Next Steps

Overview

The YOLO Developer CLI (yolo) provides commands for initializing projects, seeding requirements, running autonomous development sprints, and monitoring progress.

Basic Usage

yolo [OPTIONS] COMMAND [ARGS]...

Interactive Mode

Run yolo with no arguments to start an interactive chat session:

yolo

Or explicitly:

yolo chat

For one-shot prompts:

yolo "Summarize the current sprint status"

Global Options

Option	Description
`--version`	Show version and exit
`--help`	Show help message and exit
`-v, --verbose`	Enable verbose output
`-q, --quiet`	Suppress non-essential output
`--config PATH`	Use specific config file

Command Summary

Command	Description
`yolo init`	Initialize a new YOLO project
`yolo chat`	Start interactive chat or run one-shot prompts
`yolo integrate`	Integrate MCP clients (Codex, Claude Code, Cursor, VS Code)
`yolo seed`	Seed requirements for development
`yolo run`	Execute autonomous development sprint
`yolo status`	Display current sprint status
`yolo logs`	View agent activity logs
`yolo config`	Manage project configuration
`yolo tools`	Manage external CLI tool integrations
`yolo tune`	Adjust quality thresholds
`yolo mcp`	Start MCP server for Claude Code
`yolo scan`	Scan existing project for brownfield context
`yolo git`	Local git operations
`yolo pr`	Pull request operations
`yolo issue`	Issue operations
`yolo release`	Release operations
`yolo workflow`	GitHub workflow automation
`yolo import`	Import GitHub issues
`yolo gather`	Interactive requirements gathering
`yolo web`	Web dashboard

yolo chat

Start an interactive chat session or run a one-shot prompt.

Synopsis

yolo chat [PROMPT...]

Examples

Interactive mode:

yolo chat

One-shot prompt:

yolo chat "Summarize the current sprint status"

Pipe input:

echo "Draft release notes" | yolo chat

yolo integrate

Configure MCP client settings for external AI tools.

Synopsis

yolo integrate <client> [OPTIONS]

Options

Option	Description
`--config-path, -c`	Override default config path
`--project-dir, -p`	Project directory for `uv run` fallback
`--dry-run`	Show JSON without writing
`--force`	Overwrite existing MCP entry
`--yes, -y`	Skip confirmation prompt

Examples

yolo integrate claude-code
yolo integrate codex --dry-run
yolo integrate cursor --config-path /custom/settings.json --yes
yolo integrate vscode --force

yolo init

Initialize a new YOLO Developer project in the current directory.

Synopsis

yolo init [OPTIONS] [PATH]

Options

Option	Type	Default	Description
`--name, -n`	TEXT	Directory name	Project name
`--author, -a`	TEXT	git config	Author name for pyproject.toml
`--email, -e`	TEXT	git config	Author email for pyproject.toml
`--interactive, -i`	FLAG	False	Prompt for project details
`--no-input`	FLAG	False	Use defaults without prompting
`--existing, --brownfield`	FLAG	False	Add YOLO to existing project
`--scan-only`	FLAG	False	Scan existing project without changes
`--non-interactive`	FLAG	False	Skip brownfield prompts
`--hint`	TEXT	None	Hint about project type
`--skip-git`	FLAG	False	Skip git repository prompts
`--skip-github`	FLAG	False	Skip GitHub repository creation prompts

Git Repository Features

The init command automatically handles git repository setup:

Detection: Checks if directory is a git repository
Initialization: Offers to run git init if not initialized
Remote Detection: Displays configured remote repositories
GitHub Creation: Creates a new GitHub repository via gh CLI (if available)
Initial Commit: Creates an initial commit with project files
Push: Pushes initial commit to remote repository

Examples

Basic initialization:

yolo init

Output:

Initializing YOLO Developer project...

? Project name: my-api
? Author name: Developer
? Author email: dev@example.com

This directory is not a git repository. Initialize git? [Y/n] y
Git repository initialized!

           Git Repository Status
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Property     ┃ Value               ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ Git Status   │ Initialized         │
│ Remotes      │ None configured     │
└──────────────┴─────────────────────┘

Remote Repository Options:
  1. Create a new GitHub repository
  2. Add an existing remote URL
  3. Skip remote setup
Choose an option [3]:

Creating configuration...
  ✓ Created yolo.yaml
  ✓ Created .yolo/ directory
  ✓ Initialized memory store

Create initial commit with project files? [Y/n] y
Initial commit created!

Project initialized successfully!

Skip git prompts:

yolo init --skip-git

Skip GitHub prompts only:

yolo init --skip-github

Fully automated (no prompts):

yolo init --no-input

Brownfield initialization:

yolo init --brownfield

Scan only (no changes):

yolo init --brownfield --scan-only

Files Created

File	Description
`yolo.yaml`	Project configuration
`.yolo/`	YOLO data directory
`.yolo/memory/`	ChromaDB vector store
`.yolo/cache/`	Agent response cache

yolo seed

Seed requirements for autonomous development.

Synopsis

yolo seed [OPTIONS] [FILE]

Arguments

Argument	Type	Required	Description
`FILE`	PATH	No*	Path to requirements document

*Required unless --text is provided.

Options

Option	Type	Default	Description
`--text, -t`	TEXT	None	Provide requirements as inline text
`--format, -f`	CHOICE	auto	Input format: auto, markdown, text
`--validate-only`	FLAG	False	Validate without storing seed
`--skip-validation`	FLAG	False	Skip ambiguity/contradiction checks
`--output, -o`	PATH	None	Export parsed requirements to file

Examples

Seed from file:

yolo seed requirements.md

Output:

Parsing requirements document...
  ✓ Parsed 12 requirements

Running validation...
  ✓ No ambiguities detected
  ✓ No contradictions found
  ✓ SOP constraints validated

Seed Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Requirements: 12 total
    - Functional: 8
    - Non-Functional: 3
    - Constraints: 1
  Quality Score: 0.94

Seed ID: seed_a1b2c3d4-e5f6-7890-abcd-ef1234567890

Ready to run: yolo run

Seed from inline text:

yolo seed --text "Build a REST API with user authentication using JWT tokens"

Validate without seeding:

yolo seed requirements.md --validate-only

Output with ambiguities detected:

Parsing requirements document...
  ✓ Parsed 8 requirements

Running validation...
  ⚠ 2 ambiguities detected:
    1. "fast response times" - What is considered fast? (< 100ms? < 500ms?)
    2. "support many users" - Specific concurrency target needed

  ✓ No contradictions found
  ✓ SOP constraints validated

Clarification questions generated:
  Q1: What response time threshold defines "fast"?
      Suggestions: < 100ms, < 200ms, < 500ms
  Q2: How many concurrent users should be supported?
      Suggestions: 100, 1000, 10000

Fix ambiguities and re-run, or use --skip-validation to proceed.

Input Formats

Markdown (recommended):

# Project Requirements

## Functional Requirements
- User can register with email
- User can login with password

## Non-Functional Requirements
- Response time < 200ms
- 99.9% uptime

## Constraints
- Must use PostgreSQL

Plain text:

User Management System

The system must allow users to register with their email address.
Users must be able to login with a password.
Response times should be under 200ms.
The system must use PostgreSQL for data storage.

yolo run

Execute an autonomous development sprint.

Synopsis

yolo run [OPTIONS]

Options

Option	Type	Default	Description
`--dry-run, -d`	FLAG	False	Validate configuration and seed without running
`--verbose, -v`	FLAG	False	Show detailed output
`--json, -j`	FLAG	False	Output JSON summary
`--resume, -r`	FLAG	False	Resume from last checkpoint
`--thread-id, -t`	TEXT	None	Use specific checkpoint thread ID
`--continue`	FLAG	False	Continue from last checkpoint (alias for `--resume`)
`--agents`	TEXT	None	Comma-separated list of agents to run (accepted but not yet enforced)
`--max-iterations`	INT	None	Maximum iterations per agent (accepted but not yet enforced)
`--timeout`	INT	None	Timeout in seconds per agent (accepted but not yet enforced)
`--watch`	FLAG	False	Watch mode (accepted but not yet enforced)
`--output-dir`	PATH	None	Output directory for artifacts (accepted but not yet enforced)

Examples

Dry run (no changes):

yolo run --dry-run

Resume from checkpoint:

yolo run --resume

Use a specific thread ID:

yolo run --thread-id my-session

Agent Execution Order

Analyst - Requirement crystallization
PM - Story generation
Architect - System design
Dev - Implementation
TEA - Test validation
SM - Orchestration (runs throughout)

yolo status

Display current sprint status and progress.

Synopsis

yolo status [OPTIONS]

Options

Option	Type	Default	Description
`--format, -f`	CHOICE	table	Output format: table, json, yaml
`--json, -j`	FLAG	False	Output JSON (alias for `--format json`)
`--health, -H`	FLAG	False	Show only health metrics
`--sessions, -s`	FLAG	False	Show only session list
`--verbose, -v`	FLAG	False	Show detailed health metrics

Note: --agents, --gates, --stories, --watch, and --refresh are accepted but currently ignored (a warning is shown).

Examples

Basic status:

yolo status

JSON output for scripting:

yolo status --format json

yolo logs

View agent activity logs and audit trail.

Synopsis

yolo logs [OPTIONS]

Options

Option	Type	Default	Description
`--agent, -a`	TEXT	All	Filter by agent name
`--since, -s`	TEXT	None	Show logs since time (e.g., 1h, 30m)
`--type, -t`	TEXT	None	Filter by decision type
`--limit, -n`	INT	20	Maximum number of entries
`--all, -A`	FLAG	False	Show all entries
`--verbose, -v`	FLAG	False	Show full details
`--json, -j`	FLAG	False	Output JSON to stdout
`--format`	CHOICE	text	Output format: text or json
`--export`	PATH	None	Export JSON output to a file

Examples

View recent logs:

yolo logs

Output:

2024-01-15 10:23:45 [INFO] [ANALYST] Starting requirement analysis
2024-01-15 10:23:47 [INFO] [ANALYST] Parsing 12 requirements
2024-01-15 10:24:12 [INFO] [ANALYST] Crystallized: "User registration" → 3 specs
2024-01-15 10:24:35 [INFO] [ANALYST] Crystallized: "User authentication" → 2 specs
2024-01-15 10:25:02 [WARN] [ANALYST] Ambiguity detected: "fast response"
2024-01-15 10:25:03 [INFO] [ANALYST] Generated clarification question
2024-01-15 10:26:19 [INFO] [ANALYST] Analysis complete: 12 requirements → 18 specs
2024-01-15 10:26:20 [INFO] [PM] Starting story generation
2024-01-15 10:26:45 [INFO] [PM] Created story: US-001 User Registration
2024-01-15 10:27:02 [INFO] [PM] Created story: US-002 User Authentication

Filter by agent:

yolo logs --agent dev

Export to JSON:

yolo logs --export audit.json --format json

Output (audit.json):

{
  "entries": [
    {
      "timestamp": "2024-01-15T10:23:45Z",
      "level": "INFO",
      "agent": "ANALYST",
      "message": "Starting requirement analysis",
      "context": {
        "seed_id": "seed_abc123",
        "requirement_count": 12
      }
    },
    {
      "timestamp": "2024-01-15T10:24:12Z",
      "level": "INFO",
      "agent": "ANALYST",
      "message": "Crystallized requirement",
      "context": {
        "original": "User registration",
        "specs_generated": 3,
        "confidence": 0.92
      }
    }
  ]
}

yolo config

Manage project configuration.

Synopsis

yolo config [COMMAND] [OPTIONS]

Commands

Command	Description
`show`	Display current configuration
`set`	Set a configuration value
`get`	Get a specific configuration value
`reset`	Reset to default configuration
`validate`	Validate configuration file
`export`	Export configuration to a YAML file
`import`	Import configuration from a YAML file

Examples

Show configuration:

yolo config show

Output:

project_name: my-api
llm:
  provider: auto
  cheap_model: gpt-5.2-instant
  premium_model: claude-sonnet-4-20250514
  best_model: claude-opus-4-5-20251101
  openai_api_key: "**********" (configured)
  anthropic_api_key: "**********" (configured)
  openai:
    code_model: gpt-5.2-pro
  hybrid:
    enabled: false
quality:
  test_coverage_threshold: 0.8
  gate_pass_threshold: 0.7
memory:
  persist_path: .yolo/memory
  vector_store_type: chromadb
  graph_store_type: json
agents:
  max_iterations: 10
  timeout_seconds: 300

Set a value:

yolo config set quality.test_coverage_threshold 0.9

Get a specific value:

yolo config get llm.premium_model

Output:

claude-sonnet-4-20250514

Validate configuration:

yolo config validate

Output:

Validating yolo.yaml...
  ✓ Schema valid
  ✓ API keys configured
  ✓ Memory directory writable
  ✓ All settings valid

Configuration is valid.

Export configuration:

yolo config export -o yolo-config-export.yaml

Import configuration:

yolo config import yolo-config-export.yaml

yolo tools

Manage external CLI tool integrations like Claude Code and Aider.

Synopsis

yolo tools [OPTIONS] [COMMAND]

Commands

Command	Description
`status`	Show tool availability and configuration

Options

Option	Type	Default	Description
`--json, -j`	FLAG	False	Output as JSON

Examples

Show tool status:

yolo tools

Output:

                    External CLI Tools
┏━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Tool         ┃ Enabled ┃ Available ┃ Binary              ┃ Timeout ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ claude_code  │   Yes   │    Yes    │ /usr/local/bin/claude │  300s │
│ aider        │   No    │    No     │ aider (not found)     │  300s │
└──────────────┴─────────┴───────────┴─────────────────────┴─────────┘

JSON output:

yolo tools --json

Output:

{
  "tools": [
    {
      "name": "claude_code",
      "enabled": true,
      "binary": "claude",
      "available": true,
      "path": "/usr/local/bin/claude",
      "timeout": 300,
      "output_format": "json"
    },
    {
      "name": "aider",
      "enabled": false,
      "binary": "aider",
      "available": false,
      "path": null,
      "timeout": 300,
      "output_format": "json"
    }
  ],
  "status": "success"
}

Configuration

Tools are configured in yolo.yaml:

tools:
  claude_code:
    enabled: true
    path: /custom/path/to/claude  # optional
    timeout: 300
    output_format: json
    extra_args: []
  aider:
    enabled: false

Or via environment variables:

export YOLO_TOOLS__CLAUDE_CODE__ENABLED=true
export YOLO_TOOLS__CLAUDE_CODE__TIMEOUT=600
export YOLO_TOOLS__AIDER__ENABLED=true

yolo tune

Customize agent templates and behaviors.

Synopsis

yolo tune [AGENT_NAME] [OPTIONS]

Options

Option	Type	Default	Description
`--list, -l`	FLAG	False	List all configurable agents
`--edit, -e`	FLAG	False	Edit the agent template in `$EDITOR`
`--reset, -r`	FLAG	False	Reset the agent template to defaults
`--export`	PATH	None	Export the agent template to a file
`--import`	PATH	None	Import the agent template from a file
`--json, -j`	FLAG	False	Output template as JSON

Note: quality threshold tuning is not yet supported in this command. Use yolo config set quality.* to adjust thresholds.

Examples

List agents:

yolo tune --list

Show an agent template:

yolo tune analyst

Edit an agent template:

yolo tune analyst --edit

Export/import templates:

yolo tune analyst --export analyst.yaml
yolo tune analyst --import analyst.yaml

yolo mcp

Start MCP server for Claude Code integration.

Synopsis

yolo mcp [OPTIONS]

Options

Option	Type	Default	Description
`--transport, -t`	CHOICE	stdio	Transport: stdio, http
`--port, -p`	INT	8080	Port for HTTP transport
`--host`	TEXT	127.0.0.1	Host for HTTP transport

Examples

Start with STDIO (for Claude Desktop):

yolo mcp

Start with HTTP transport:

yolo mcp --transport http --port 8080

Output:

Starting YOLO Developer MCP Server...
  Transport: HTTP
  Address: http://127.0.0.1:8080

Available tools:
  - yolo_seed: Provide seed requirements
  - yolo_run: Execute sprint
  - yolo_status: Get status
  - yolo_audit: Access audit

Server ready. Press Ctrl+C to stop.

See MCP Integration for detailed usage.

yolo scan

Scan an existing repository and optionally write .yolo/project-context.yaml.

Synopsis

yolo scan [OPTIONS] [PATH]

Options

Option	Type	Default	Description
`--scan-depth`	INT	3	Directory depth to scan
`--max-files`	INT	1000	Maximum files to analyze
`--git-history/--no-git-history`	FLAG	from config	Include git history analysis
`--interactive, -i`	FLAG	False	Prompt for ambiguous findings
`--hint`	TEXT	None	Hint about project type
`--refresh`	FLAG	False	Overwrite existing project-context.yaml
`--write-context/--no-write-context`	FLAG	True	Write project context file

Examples

yolo scan
yolo scan --refresh
yolo scan --max-files 200 --scan-depth 4

yolo git

Manage local Git operations.

yolo git status
yolo git commit -m "feat: update"
yolo git push

yolo pr

Manage pull requests.

yolo pr create --title "Title" --body "Body"
yolo pr merge 123 --method squash

yolo issue

Manage GitHub issues.

yolo issue create --title "Bug" --body "Details"
yolo issue close 123 --comment "Fixed in PR #456"

yolo release

Create GitHub releases.

yolo release create --tag v1.2.0 --name "Release 1.2.0" --body "Notes"

yolo workflow

Automate story workflows.

yolo workflow start US-001 --title "Add endpoint" --description "..."
yolo workflow complete US-001 --title "Add endpoint" --description "..." --commit "feat: add endpoint"

yolo import

Import GitHub issues and convert them into user stories.

yolo import issue 42
yolo import preview 42
yolo import issues --label "ready" --auto-seed

Common options:

--repo owner/repo: override repository
--auto-seed: write seed file to .yolo/imported-issues/
--preview: preview only
--output: export story to file

yolo gather

Interactive requirements gathering with the Analyst agent.

yolo gather start my-project --description "Build a task manager"
yolo gather list
yolo gather export 20250122093000 --format markdown --output requirements.md

yolo web

Start the local web dashboard and API.

yolo web start
yolo web start --port 8080 --host 0.0.0.0

Exit Codes

Code	Description
0	Success
1	General error
2	Configuration error
3	Validation error
4	API error (LLM)
5	Quality gate failure
130	Interrupted (Ctrl+C)

Environment Variables

All configuration can be overridden via environment variables using the YOLO_ prefix:

Variable	Description
`YOLO_PROJECT_NAME`	Project name
`YOLO_LLM__PROVIDER`	Primary LLM provider (auto/openai/anthropic/hybrid)
`YOLO_LLM__CHEAP_MODEL`	Model for routine tasks
`YOLO_LLM__PREMIUM_MODEL`	Model for complex tasks
`YOLO_LLM__BEST_MODEL`	Model for critical tasks
`YOLO_LLM__OPENAI__API_KEY`	OpenAI API key (preferred)
`YOLO_LLM__OPENAI_API_KEY`	OpenAI API key (legacy)
`YOLO_LLM__ANTHROPIC_API_KEY`	Anthropic API key
`YOLO_LLM__OPENAI__CODE_MODEL`	OpenAI model for code tasks
`YOLO_LLM__HYBRID__ENABLED`	Enable hybrid routing
`YOLO_QUALITY__TEST_COVERAGE_THRESHOLD`	Coverage threshold
`YOLO_QUALITY__GATE_PASS_THRESHOLD`	Gate pass threshold
`YOLO_MEMORY__PERSIST_PATH`	Memory storage path
`YOLO_MEMORY__VECTOR_STORE_TYPE`	Vector store backend
`YOLO_MEMORY__GRAPH_STORE_TYPE`	Graph store backend
`YOLO_BROWNFIELD__SCAN_DEPTH`	Brownfield scan depth
`YOLO_BROWNFIELD__MAX_FILES_TO_ANALYZE`	Brownfield scan file limit
`YOLO_GITHUB__TOKEN`	GitHub token
`YOLO_GITHUB__REPOSITORY`	GitHub repo slug (owner/repo)

Next Steps

MCP Integration - Use with Claude Code
Python SDK - Programmatic API
Configuration - All options

CLI Reference

Table of contents

Overview

Basic Usage

Interactive Mode

Global Options

Command Summary

yolo chat

Synopsis

Examples

yolo integrate

Synopsis

Options

Examples

yolo init

Synopsis

Options

Git Repository Features

Examples

Files Created

yolo seed

Synopsis

Arguments

Options

Examples

Input Formats

yolo run

Synopsis

Options

Examples

Agent Execution Order

yolo status

Synopsis

Options

Examples

yolo logs

Synopsis

Options

Examples

yolo config

Synopsis

Commands

Examples

yolo tools

Synopsis

Commands

Options

Examples

Configuration

yolo tune

Synopsis

Options

Examples

yolo mcp

Synopsis

Options

Examples

yolo scan

Synopsis

Options

Examples

yolo git

yolo pr

yolo issue

yolo release

yolo workflow

yolo import

yolo gather

yolo web

Exit Codes

Exit Codes

Environment Variables

Next Steps

Table of contents