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