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