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:

```bash
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)
```bash
claude -p "query" --output-format json
# {"result": "...", "session_id": "...", "usage": {...}}
```

### Streaming (for real-time monitoring)
```bash
claude -p "query" --output-format stream-json
# Newline-delimited JSON events
```

### Structured Output (schema validation)
```bash
claude -p "Extract data" \
  --output-format json \
  --json-schema '{"type":"object","properties":{...}}'
```

## Headless Agent Pattern (CRITICAL)

Proper headless agent spawn:

```bash
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
```bash
claude -p "Run tests and fix failures" \
  --dangerously-skip-permissions \
  --max-turns 50 \
  --output-format json | jq '.result'
```

### Piped Input
```bash
cat error.log | claude -p "Find root cause"
gh pr diff | claude -p "Review for security"
```

### Multi-turn Session
```bash
id=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude -p "Continue" --resume "$id"
```

### Stream Monitoring
```bash
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 |