cli-reference

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":{...}}'

Headless Agent Pattern (CRITICAL)

Proper headless agent spawn:

claude -p "$TASK_PROMPT" \
  --session-id "$UUID" \
  --dangerously-skip-permissions \
  --max-turns 100 \
  --output-format stream-json \
  --agents '{...}' \
  --append-system-prompt "Context: ..."

Missing any of these causes hangs:

• --session-id - Track the session
• --dangerously-skip-permissions - Headless requires this
• --max-turns - Prevents infinite loops

Common Patterns

CI/CD Automation

claude -p "Run tests and fix failures" \
  --dangerously-skip-permissions \
  --max-turns 50 \
  --output-format json | jq '.result'

Piped Input

cat error.log | claude -p "Find root cause"
gh pr diff | claude -p "Review for security"

Multi-turn Session

id=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude -p "Continue" --resume "$id"

Stream Monitoring

claude -p "Long task" \
  --output-format stream-json \
  --include-partial-messages | while read -r line; do
    echo "$line" | jq '.type'
done

Keyboard Shortcuts (Interactive)

| Shortcut | Action |

|----------|--------|

| Ctrl+C | Cancel current |

| Ctrl+D | Exit |

| Ctrl+R | Reverse search history |

| Esc Esc | Rewind changes |

| Shift+Tab | Toggle permission mode |

Quick Commands

| Prefix | Action |

|--------|--------|

| / | Slash command |

| ! | Bash mode |

| # | Add to memory |

| @ | File mention |