Claude Code CLI Reference

CLI Commands

Interactive Mode

Start interactive REPL:

bash

claude

Start with initial prompt:

bash

claude "query"

Non-Interactive Mode

Query via SDK, then exit:

bash

claude -p "query"
claude --print "query"

Process piped content:

bash

cat file | claude -p "query"
echo "content" | claude -p "analyze this"

Continue most recent conversation:

bash

claude -c
claude --continue

Continue via SDK:

bash

claude -c -p "query"

Resume session by ID:

bash

claude -r "<session-id>" "query"
claude --resume "<session-id>" "query"

Maintenance

Update to latest version:

bash

claude update

Configure MCP servers:

bash

claude mcp

Check installation health:

bash

claude --doctor

Migrate installer:

bash

claude migrate-installer

Key CLI Flags

Essential Flags

Flag	Short	Purpose	Example
`--print`	`-p`	Print response without interactive mode	`claude -p "task"`
`--continue`	`-c`	Continue most recent conversation	`claude -c "follow up"`
`--resume`	`-r`	Resume session by ID	`claude -r abc123 "task"`
`--help`	`-h`	Show help information	`claude --help`
`--version`	`-v`	Show version	`claude --version`

Configuration Flags

Flag	Purpose	Example
`--add-dir`	Add working directories for access	`claude --add-dir /path/to/dir`
`--agents`	Define custom subagents dynamically via JSON	`claude --agents '[{...}]'`
`--model`	Set model with alias or full name	`claude --model opus`
`--max-turns`	Limit agentic turns in non-interactive mode	`claude --max-turns 5`
`--permission-mode`	Begin in specified permission mode	`claude --permission-mode acceptAll`
`--allowedTools`	Specify permitted tools	`claude --allowedTools "Bash,Read"`

Output & Format Flags

Flag	Purpose	Example
`--output-format`	Specify format (text, json, stream-json)	`claude -p --output-format json`
`--input-format`	Specify input format	`claude --input-format stream-json`
`--verbose`	Enable detailed logging for debugging	`claude --verbose`
`--debug`	Enable debug mode	`claude --debug`

Advanced Flags

Flag	Purpose	Example
`--mcp-config`	Load MCP servers from JSON file	`claude --mcp-config servers.json`
`--append-system-prompt`	Append text to system prompt	`claude --append-system-prompt "Be concise"`
`--compact`	Start with compacted context	`claude --compact`
`--no-cache`	Disable prompt caching	`claude --no-cache`

Agents Flag Format

Custom subagents require JSON with:

•description: Purpose of the subagent
•prompt: System prompt for the subagent
•tools (optional): Array of allowed tools
•model (optional): Model to use

Example:

bash

claude --agents '[{
  "description": "Code reviewer",
  "prompt": "Review code for quality and security",
  "tools": ["Read", "Grep", "Glob"],
  "model": "sonnet"
}]'

Permission Modes

Mode	Description
`ask`	Ask for permission for each operation (default)
`acceptAll`	Accept all operations automatically
`acceptEdits`	Auto-accept file edits, ask for bash
`acceptCommands`	Auto-accept bash, ask for edits
`denyAll`	Deny all operations

Example:

bash

claude --permission-mode acceptEdits -p "refactor the code"

Model Aliases

Alias	Full Model Name
`sonnet`	claude-sonnet-4-5-20250929
`opus`	claude-opus-4-5-20250514
`haiku`	claude-haiku-4-5-20250815

Example:

bash

claude --model opus "complex reasoning task"
claude --model haiku -p "simple query"

Output Formats

Text (Default)

Plain text output suitable for reading:

bash

claude -p "explain this code"

JSON

Structured output with metadata:

bash

claude -p --output-format json "analyze project"

JSON structure:

json

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "duration_ms": 1234,
  "num_turns": 6,
  "result": "Response text...",
  "session_id": "abc123"
}

Stream JSON

JSONL format for real-time processing:

bash

claude -p --output-format stream-json --input-format stream-json

Environment Variables

Key environment variables affecting CLI behavior:

Variable	Purpose
`ANTHROPIC_API_KEY`	API authentication
`CLAUDE_CODE_USE_BEDROCK`	Use AWS Bedrock
`CLAUDE_CODE_USE_VERTEX`	Use Google Vertex AI
`CLAUDE_CODE_ENABLE_TELEMETRY`	Enable telemetry
`DISABLE_PROMPT_CACHING`	Disable caching
`MAX_THINKING_TOKENS`	Enable extended thinking
`BASH_MAX_OUTPUT_LENGTH`	Limit bash output
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	Max output tokens

Common Usage Patterns

Quick Query

bash

claude -p "what does this project do?"

Automated Task

bash

claude -p "run tests and fix failures" \
  --allowedTools "Bash,Read,Edit,Write" \
  --max-turns 10 \
  --permission-mode acceptAll

Resume Previous Work

bash

claude -c "continue the refactoring"

Custom Configuration

bash

claude \
  --model sonnet \
  --permission-mode acceptEdits \
  --verbose \
  --add-dir /path/to/project

CI/CD Integration

bash

claude -p "review PR changes" \
  --output-format json \
  --allowedTools "Read,Bash" \
  --max-turns 5

MCP with Custom Servers

bash

claude --mcp-config mcp-servers.json -p "fetch user data"

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
130	Interrupted (Ctrl+C)

Tips & Tricks

Piping Input

bash

# Pipe file content
cat script.py | claude -p "explain this code"

# Pipe command output
git diff | claude -p "review these changes"

# Pipe from multiple sources
cat file1.txt file2.txt | claude -p "summarize"

Chaining Commands

bash

# With AND operator
claude -p "task 1" && claude -p "task 2"

# With OR operator
claude -p "task" || echo "Failed"

Background Execution

bash

# Run in background
claude -p "long task" &

# With output redirection
claude -p "task" > output.txt 2>&1 &

Parsing JSON Output

bash

# Extract specific field with jq
claude -p "task" --output-format json | jq -r '.result'

# Get session ID
SESSION=$(claude -p "task" --output-format json | jq -r '.session_id')

# Check cost
claude -p "task" --output-format json | jq '.total_cost_usd'

Using with Scripts

bash

#!/bin/bash

# Check if task succeeded
RESULT=$(claude -p "run tests" --output-format json)
STATUS=$(echo "$RESULT" | jq -r '.subtype')

if [ "$STATUS" = "success" ]; then
  echo "Tests passed"
else
  echo "Tests failed"
  exit 1
fi

Debugging

Enable Verbose Output

bash

claude --verbose -p "task"

Enable Debug Mode

bash

claude --debug

Check Version

bash

claude --version

View Help

bash

claude --help
claude -h

Best Practices

•Use specific flags for automation and scripts
•Enable JSON output for programmatic parsing
•Set max-turns to prevent runaway operations
•Configure permissions appropriately for security
•Use model aliases for readability
•Pipe stderr to logs for error tracking
•Check exit codes in scripts
•Use --allowedTools to restrict capabilities
•Set timeouts for long-running tasks
•Test with --verbose before production use