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