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 (Fixed in v2.0.14)

Add to ~/.claude/settings.json:

{
  "alwaysThinkingEnabled": true
}

Status: ✅ Fixed in version 2.0.14 (2025-10-11)

The sync issue between the settings file and runtime calculation layer has been fixed. The tab toggle and alwaysThinkingEnabled setting now properly sync to FL1().alwaysThinking, enabling thinking tokens without requiring the environment variable or “ultrathink” keyword.

Previous Issue (v2.0.13 and earlier): This setting was read and displayed in the UI, but didn’t sync to the runtime calculation layer (IL1().alwaysThinking). The sync code between pA().alwaysThinkingEnabled and dLA.alwaysThinking was 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.

Version History

Version 2.0.14 (2025-10-11)

Thinking Mode Fix: Fixed ultrathink + thinking toggle sync issue

The critical sync issue between the thinking mode UI toggle and the runtime calculation layer has been resolved:

What was fixed:

• The settings file alwaysThinkingEnabled now properly syncs to the runtime config (FL1().alwaysThinking)
• The tab toggle now actually enables thinking mode without requiring environment variables or keywords
• Missing sync code between pA().alwaysThinkingEnabled and dLA.alwaysThinking has been implemented

Impact:

• ✅ Settings file method (~/.claude/settings.json with "alwaysThinkingEnabled": true) now works correctly
• ✅ Tab toggle in UI now properly enables thinking tokens for all subsequent turns
• ✅ No longer need to use MAX_THINKING_TOKENS environment variable as a workaround
• ✅ No longer need to type “ultrathink” keyword in every message

Other changes in 2.0.14:

• Fix @-mentioning MCP servers to toggle them on/off
• Improve permission checks for bash with inline env vars
• Reduce unnecessary logins
• Document –system-prompt
• Several improvements to rendering
• Plugins UI polish

References:

• Release notes: https://docs.claude.com/en/release-notes/changelog
• Previous analysis: Deep Dive: Thinking Mode