cli-reference

SKILL.md

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