CLI Reference

Claude Code CLI Reference

CLI Commands

Interactive Mode

Start interactive REPL:

claude

Start with initial prompt:

claude "query"

Non-Interactive Mode

Query via SDK, then exit:

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

Process piped content:

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

Continue most recent conversation:

claude -c
claude --continue

Continue via SDK:

claude -c -p "query"

Resume session by ID:

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

Maintenance

Update to latest version:

claude update

Configure MCP servers:

claude mcp

Check installation health:

claude --doctor

Migrate installer:

claude migrate-installer

Key CLI Flags

Essential Flags

Configuration Flags

Output & Format Flags

Advanced Flags

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:

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

Permission Modes

Example:

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

Model Aliases

Example:

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

Output Formats

Text (Default)

Plain text output suitable for reading:

claude -p "explain this code"

JSON

Structured output with metadata:

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

JSON structure:

{
  "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:

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

Environment Variables

Key environment variables affecting CLI behavior:

Common Usage Patterns

Quick Query

claude -p "what does this project do?"

Automated Task

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

Resume Previous Work

claude -c "continue the refactoring"

Custom Configuration

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

CI/CD Integration

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

MCP with Custom Servers

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

Exit Codes

Tips & Tricks

Piping Input

# 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

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

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

Background Execution

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

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

Parsing JSON Output

# 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

#!/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

claude --verbose -p "task"

Enable Debug Mode

claude --debug

Check Version

claude --version

View Help

claude --help
claude -h

Best Practices

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