/cli-reference

name: cli-reference
description: Claude Code CLI commands, flags, headless mode, and automation patterns
allowed-tools: [Read]

CLI Reference

Complete reference for Claude Code command-line interface.

When to Use

• "What CLI flags are available?"
• "How do I use headless mode?"
• "Claude in automation/CI/CD"
• "Output format options"
• "System prompt via CLI"
• "How do I spawn agents properly?"

Core Commands

| Command | Description | Example | |---------|-------------|---------| | `claude` | Start interactive REPL | `claude` | | `claude "query"` | REPL with initial prompt | `claude "explain this project"` | | `claude -p "query"` | Headless mode (SDK) | `claude -p "explain function"` | | `cat file \| claude -p` | Process piped content | `cat logs.txt \| claude -p "explain"` | | `claude -c` | Continue most recent | `claude -c` | | `claude -c -p "query"` | Continue via SDK | `claude -c -p "check types"` | | `claude -r "id" "query"` | Resume session | `claude -r "auth" "finish PR"` | | `claude update` | Update version | `claude update` | | `claude mcp` | Configure MCP servers | See MCP docs |

Session Control

| Flag | Description | Example | |------|-------------|---------| | `--continue, -c` | Load most recent conversation | `claude --continue` | | `--resume, -r` | Resume session by ID/name | `claude --resume auth-refactor` | | `--session-id` | Use specific UUID | `claude --session-id "550e8400-..."` | | `--fork-session` | Create new session on resume | `claude --resume abc --fork-session` |

Headless Mode (Critical for Agents)

| Flag | Description | Example | |------|-------------|---------| | `--print, -p` | Non-interactive, exit after | `claude -p "query"` | | `--output-format` | `text`, `json`, `stream-json` | `claude -p --output-format json` | | `--max-turns` | Limit agentic turns | `claude -p --max-turns 100 "query"` | | `--verbose` | Full turn-by-turn output | `claude --verbose` | | `--dangerously-skip-permissions` | Skip permission prompts | `claude -p --dangerously-skip-permissions` | | `--include-partial-messages` | Include streaming events | `claude -p --output-format stream-json --include-partial-messages` | | `--input-format` | Input format (text/stream-json) | `claude -p --input-format stream-json` |

Tool Control

| Flag | Description | Example | |------|-------------|---------| | `--allowedTools` | Auto-approve these tools | `"Bash(git log:*)" "Read"` | | `--disallowedTools` | Block these tools | `"Bash(rm:*)" "Edit"` | | `--tools` | Only allow these tools | `--tools "Bash,Edit,Read"` |

Subagent Definition (--agents flag)

Define custom subagents inline via JSON:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors and provide fixes."
  }
}'

Agent Fields

| Field | Required | Description | |-------|----------|-------------| | `description` | Yes | When to invoke this agent | | `prompt` | Yes | System prompt for behavior | | `tools` | No | Allowed tools (inherits all if omitted) | | `model` | No | `sonnet`, `haiku`, or `claude-opus-4-5-20251101` |

Key Insight

When Lead uses Task tool, it auto-spawns from these definitions. No manual spawn needed.

System Prompt Customization

| Flag | Behavior | Modes | |------|----------|-------| | `--system-prompt` | **Replace** entire prompt | Interactive + Print | | `--system-prompt-file` | **Replace** from file | Print only | | `--append-system-prompt` | **Append** to default (recommended) | Interactive + Print |

**Use `--append-system-prompt`** for most cases - preserves Claude Code capabilities.

Model Selection

| Flag | Description | Example | |------|-------------|---------| | `--model` | Set model for session | `--model claude-sonnet-4-5` | | `--fallback-model` | Fallback if default overloaded | `--fallback-model sonnet` |

Aliases: `sonnet`, `opus`, `haiku`

MCP Configuration

| Flag | Description | Example | |------|-------------|---------| | `--mcp-config` | Load MCP servers from JSON | `--mcp-config ./mcp.json` | | `--strict-mcp-config` | Only use these MCP servers | `--strict-mcp-config --mcp-config ./mcp.json` |

Advanced Flags

| Flag | Description | Example | |------|-------------|---------| | `--add-dir` | Add working directories | `--add-dir ../apps ../lib` | | `--agent` | Specify agent for session | `--agent my-custom-agent` | | `--permission-mode` | Start in permission mode | `--permission-mode plan` | | `--permission-prompt-tool` | MCP tool for permissions | `--permission-prompt-tool mcp_auth` | | `--plugin-dir` | Load plugins from directory | `--plugin-dir ./my-plugins` | | `--settings` | Load settings from file/JSON | `--settings ./settings.json` | | `--setting-sources` | Which settings to load | `--setting-sources user,project` | | `--betas` | Beta API headers | `--betas interleaved-thinking` | | `--debug` | Enable debug mode | `--debug "api,hooks"` | | `--ide` | Auto-connect to IDE | `--ide` | | `--chrome` | Enable Chrome integration | `--chrome` | | `--no-chrome` | Disable Chrome for session | `--no-chrome` | | `--enable-lsp-logging` | Verbose LSP debugging | `--enable-lsp-logging` | | `--version, -v` | Output version | `claude -v` |

Output Formats

JSON (for parsing)

claude -p "query" --output-format json
# {"result": "...", "session_id": "...", "usage": {...}}

Streaming (for real-time monitoring)

claude -p "query" --output-format stream-json
# Newline-delimited JSON events

Structured Output (schema validation)

claude -p "Extract data" \
  --output-format json \
  --json-schema '{"type":"object","properties":{...}}'

Hea