---

name: cli-reference description: Complete CLI command reference for Claude Code including flags, options, and usage patterns. Use when user asks about command-line options, flags, CLI usage, or command syntax.

Claude Code CLI Reference

CLI Commands

Interactive Mode

Start interactive REPL:

Copyclaude

Start with initial prompt:

Copyclaude "query"

Non-Interactive Mode

Query via SDK, then exit:

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

Process piped content:

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

Continue most recent conversation:

Copyclaude -c
claude --continue

Continue via SDK:

Copyclaude -c -p "query"

Resume session by ID:

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

Maintenance

Update to latest version:

Copyclaude update

Configure MCP servers:

Copyclaude mcp

Check installation health:

Copyclaude --doctor

Migrate installer:

Copyclaude 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:

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

Permission Modes

Example:

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

Model Aliases

Example:

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

Output Formats

Text (Default)

Plain text output suitable for reading:

Copyclaude -p "explain this code"

JSON

Structured output with metadata:

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

JSON structure:

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

Copyclaude -p --output-format stream-json --input-format stream-json

Environment Variables

Key environment variables affecting CLI behavior:

Common Usage Patterns

Quick Query

Copyclaude -p "what does this project do?"

Automated Task

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

Resume Previous Work

Copyclaude -c "continue the refactoring"

Custom Configuration

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

CI/CD Integration

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

MCP with Custom Servers

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

Exit Codes

Tips & Tricks

Piping Input

Copy# 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

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

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

Background Execution

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

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

Parsing JSON Output

Copy# 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

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

Copyclaude --verbose -p "task"

Enable Debug Mode

Copyclaude --debug

Check Version

Copyclaude --version

View Help

Copyclaude --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