Claude Code CLI - Complete Reference

Main Command: claude [prompt]

Start interactive session (default) or non-interactive with -p/--print

All Options (Including Hidden)

MCP Commands: claude mcp <subcommand>

Configure and manage MCP servers

claude mcp serve

Start the Claude Code MCP server

Options:

• -h, --help - Display help
• -d, --debug - Enable debug mode
• --verbose - Override verbose mode setting from config

claude mcp add <name> <commandOrUrl> [args...]

Add an MCP server

Arguments:

• <name> - Server name (required)
• <commandOrUrl> - Command to run or URL (required)
• [args...] - Additional arguments (optional)

Options:

• -h, --help - Display help
• -s, --scope <scope> - Configuration scope: local (default), user, project
• -t, --transport <transport> - Transport type: stdio (default), sse, http
• -e, --env <env...> - Set environment variables (e.g. -e KEY=value)
• -H, --header <header...> - Set WebSocket headers (e.g. -H "X-Api-Key: abc123")

claude mcp remove <name>

Remove an MCP server

Arguments:

• <name> - Server name (required)

Options:

• -h, --help - Display help
• -s, --scope <scope> - Configuration scope (local, user, or project) - if not specified, removes from whichever scope it exists in

claude mcp list

List configured MCP servers with health status

Options:

• -h, --help - Display help

claude mcp get <name>

Get details about an MCP server

Arguments:

• <name> - Server name (required)

Options:

• -h, --help - Display help

claude mcp add-json <name> <json>

Add an MCP server (stdio or SSE) with a JSON string

Arguments:

• <name> - Server name (required)
• <json> - JSON configuration string (required)

Options:

• -h, --help - Display help
• -s, --scope <scope> - Configuration scope: local (default), user, project

claude mcp add-from-claude-desktop

Import MCP servers from Claude Desktop (Mac and WSL only)

Options:

• -h, --help - Display help
• -s, --scope <scope> - Configuration scope: local (default), user, project

claude mcp reset-project-choices

Reset all approved and rejected project-scoped (.mcp.json) servers within this project

Options:

• -h, --help - Display help

Plugin Commands: claude plugin <subcommand>

Manage Claude Code plugins

claude plugin validate <path>

Validate a plugin or marketplace manifest

Arguments:

• <path> - Path to plugin/manifest file (required)

Options:

• -h, --help - Display help

Utility Commands

claude migrate-installer

Migrate from global npm installation to local installation

Options:

• -h, --help - Display help

claude setup-token

Set up a long-lived authentication token (requires Claude subscription)

Options:

• -h, --help - Display help

claude doctor

Check the health of your Claude Code auto-updater

Options:

• -h, --help - Display help

claude update

Check for updates and install if available

Options:

• -h, --help - Display help

claude install [target]

Install Claude Code native build. Use [target] to specify version (stable, latest, or specific version)

Arguments:

• [target] - Version target (optional): stable, latest, or specific version number

Options:

• -h, --help - Display help
• --force - Force installation even if already installed

Examples

# Basic interactive session
claude "explain this code"

# Non-interactive with custom system prompt
claude -p --system-prompt "You are a Python expert" "review this code"

# Load system prompt from file
claude -p --system-prompt-file ./prompts/reviewer.txt "check main.py"

# Continue last conversation
claude -c

# Resume specific session
claude -r abc-123-def-456

# Fork session when resuming
claude -r abc-123-def-456 --fork-session

# Use specific model with fallback
claude -p --model opus --fallback-model sonnet "complex analysis task"

# Limit agentic turns (hidden option)
claude -p --max-turns 5 "implement feature X"

# Control thinking tokens (hidden option)
claude -p --max-thinking-tokens 2000 "solve this problem"

# JSON output with streaming
claude -p --output-format stream-json "analyze codebase"

# JSON input and output
claude -p --input-format stream-json --output-format stream-json

# Whitelist specific tools
claude -p --allowed-tools "Bash(git:*) Read Write" "commit changes"

# Blacklist tools
claude -p --disallowed-tools "Bash WebFetch" "safe operations only"

# Add custom agents
claude --agents '{"reviewer":{"description":"Code reviewer","prompt":"Review for bugs"}}' "review app.js"

# Load MCP config dynamically
claude --mcp-config /path/to/mcp.json --strict-mcp-config "use these servers only"

# Add stdio MCP server to user scope
claude mcp add my-server npx my-mcp-package -s user -e API_KEY=secret123

# Add SSE MCP server with headers
claude mcp add sse-srv https://api.example.com/mcp -t sse -s user -H "X-Api-Key: key123" -H "X-Custom: value"

# Add HTTP MCP server
claude mcp add http-srv https://mcp.example.com -t http -s project

# List all MCP servers and their health
claude mcp list

# Get details about specific server
claude mcp get my-server

# Remove MCP server (auto-detect scope)
claude mcp remove my-server

# Remove from specific scope
claude mcp remove my-server -s user

# Import MCP servers from Claude Desktop
claude mcp add-from-claude-desktop -s user

# Reset project MCP approvals
claude mcp reset-project-choices

# Validate plugin manifest
claude plugin validate ./my-plugin/manifest.json

# Setup OAuth token
claude setup-token

# Check updater health
claude doctor

# Update to latest
claude update

# Install specific version
claude install 1.2.3 --force

Notes

• Hidden options (marked with [HIDDEN]) are not shown in --help output but are fully functional
• Deprecated options (marked with [DEPRECATED]) still work but should not be used for new code
• MCP server scopes: local (project .claude/), user (~/.claude/), project (.mcp.json)
• MCP transports: stdio (stdin/stdout), sse (Server-Sent Events), http (HTTP polling)
• Permission modes vary by configuration - check docs for available modes
• Session IDs must be valid UUIDs (e.g. 550e8400-e29b-41d4-a716-446655440000)
• The --print mode skips workspace trust dialog - only use in directories you trust

Deep Dive: Thinking Mode

Architecture Overview

Claude Code has a three-layer system for thinking mode:

1. Settings File (~/.claude/settings.json)
   └─ "alwaysThinkingEnabled": true/false

2. App State (UI Layer)
   └─ thinkingEnabled: boolean (Tab toggle)

3. Runtime Config (Calculation Layer)
   └─ IL1().alwaysThinking (used for actual token calculation)

Maximum thinking tokens: 31,999 (cli.js:143446)

How to Enable Always-Think Mode

✅ Method 1: Environment Variable (RECOMMENDED - Always Works)

# Add to ~/.bashrc or ~/.zshrc
export MAX_THINKING_TOKENS=31999

# Or prefix each command
MAX_THINKING_TOKENS=31999 claude "your prompt"

Result: Every turn gets 31,999 thinking tokens automatically, no keyword needed.

⚠️ Method 2: Settings File (Currently Broken)

Add to ~/.claude/settings.json:

{
  "alwaysThinkingEnabled": true
}

Issue: This setting is read and displayed in the UI, but doesn’t sync to the runtime calculation layer (IL1().alwaysThinking). The sync code between pA().alwaysThinkingEnabled and dLA.alwaysThinking is missing (cli.js:82291).

✅ Method 3: Per-Message Keyword

Type any of these in your message:

• ultrathink
• think ultra hard
• think ultrahard

Result: That specific turn gets 31,999 thinking tokens.

✅ Method 4: Command-line Flag (Print Mode Only)

claude -p --max-thinking-tokens 31999 "your prompt"

Priority Hierarchy

When calculating thinking tokens (cli.js:143365-143377):

1. MAX_THINKING_TOKENS env var ← Highest priority (overrides everything)
2. --max-thinking-tokens flag (print mode only)
3. “ultrathink” keyword in message content
4. IL1().alwaysThinking (from runtime config, not settings file)
5. Default: 0 (no thinking)

Token Calculation Flow

function hS(A, B, Q) {
  // 1. Check environment variable first
  if (process.env.MAX_THINKING_TOKENS) {
    return parseInt(process.env.MAX_THINKING_TOKENS, 10);
  }

  // 2. Check runtime config (broken: doesn't sync from settings)
  if (Q === "repl_main_thread") {
    if (IL1().alwaysThinking) return 31999;
  }

  // 3. Check for "ultrathink" keyword in messages
  return Math.max(
    ...A.filter((Z) => Z.type === "user" && !Z.isMeta).map(Ww4),
    B ?? 0,
  );
}

Tab Toggle Behavior

What it does:

• Controls UI display (“Thinking on” / “Thinking off”)
• Saves to settings file when changed (cli.js:456481)
• Initialized from settings on startup (cli.js:143417)

What it doesn’t do:

• Doesn’t directly enable thinking tokens
• Only enables detection of “ultrathink” keyword in messages
• Without keyword in message: 0 thinking tokens (even when toggle is ON)

API Implementation

When MAX_THINKING_TOKENS=31999 or “ultrathink” is detected:

// cli.js:442607, 442622
{
  model: "claude-sonnet-4-5-20250929",
  messages: [...],
  thinking: {
    type: "enabled",
    budget_tokens: 31999  // ← Sent to API
  },
  max_tokens: 8192,
  ...
}

Comparison Table

Additional Technical Details

• WebFetch HTML conversion: Uses hardcoded 512 tokens (cli.js:443019)
• Thinking blocks streaming: content_block_start with type: "thinking" (cli.js:442684-442685)
• Settings load: pA() → gh() → pD8() (cli.js:449461-449489)
• Runtime config init: JL1() initializes dLA to {alwaysThinking: false} (cli.js:82291)
• Missing sync: No code converts pA().alwaysThinkingEnabled → dLA.alwaysThinking

Recommended Setup

Add to your shell profile (~/.bashrc or ~/.zshrc):

# Enable extended thinking mode for all Claude Code sessions
export MAX_THINKING_TOKENS=31999

This is the most reliable method and works for all use cases.