Claude Code CLI — Complete Reference

This document is a REFERENCE — not a guide, not an overview. Every flag, every command, every option is documented. Based on official Anthropic documentation (March 2026).

Installation

Supported Platforms

Claude Code is available for:

• macOS 13.0 or newer (Intel and Apple Silicon)
• Linux x86_64 and aarch64 (glibc systems)
• Alpine Linux and musl-based distributions (special handling required)
• Windows 10/11 with Git Bash
• WSL1/WSL2 on Windows

Installation Methods

Shell Installer (macOS / Linux)

curl -fsSL https://claude.ai/install.sh | bash

The script:

• Checks system requirements
• Auto-detects CPU architecture
• Installs to ~/.local/bin/claude
• Detects your shell profile and adds PATH

After installation:

• Restart terminal OR
• Run source ~/.zshrc / source ~/.bashrc

PowerShell Installer (Windows)

irm https://claude.ai/install.ps1 | iex

The script:

• Checks system requirements
• Detects Windows architecture
• Installs to %USERPROFILE%\.local\bin\claude.exe
• Adds to User PATH environment variable

After installation: Restart terminal.

CMD Installer (Windows)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Homebrew (macOS)

brew install --cask claude-code

WinGet (Windows)

winget install Anthropic.ClaudeCode

NPM (All platforms, deprecated)

npm install -g @anthropic-ai/claude-code

NPM installation is deprecated. Use the shell/PowerShell installer instead. They are 3-4x faster.

System Requirements

Verification After Installation

claude --version

Should output version number, e.g., claude 2.1.42.

CLI Commands

CLI Flags — Complete Reference

General Flags

Debug categories:

• api — API calls
• mcp — MCP servers
• hooks — Lifecycle hooks
• file — File operations
• statsig — Feature flags

Negate with ! (e.g., "!statsig,!file").

Session Management

Directory and File Management

Model and Agent Configuration

Permission and Security

Tool Control

Syntax:

• "Bash" — all bash commands
• "Bash(git log *)" — only git log pattern matching
• "Read" — read tool completely
• "" — disable all tools

Browser Integration

System Prompt Customization

--system-prompt and --system-prompt-file are mutually exclusive. Append flags can be combined with either replacement flag.

Configuration Files

Print Mode (Non-Interactive)

IDE and Development

Plugins and Extensions

MCP and Channels (Research Preview)

Maintenance and Initialization

API and Advanced Options

Built-In Keyboard Shortcuts (Interactive Mode)

General Controls

Text Editing

Multiline Input (Various Methods)

Shift+Enter works out-of-the-box on iTerm2, WezTerm, Ghostty, Kitty. Other terminals: run /terminal-setup to configure.

Quick Commands (Prefix Notation)

Vim Editor Mode

Enable with /vim command or /config.

Mode Switching

Navigation (NORMAL Mode)

Editing (NORMAL Mode)

Text Objects

Voice Input

Transcript inserts at cursor. Key is rebindable.

Environment Variables

API and Authentication

Network and Proxy

Feature Flags and Behavior

Terminal and IDE

Development and Debugging

Configuration Files

Storage Locations

Settings File Structure

{
  "model": "claude-opus-4-1",
  "tools": ["Read", "Bash", "Edit", "Glob", "Grep"],
  "allowedTools": [
    "Bash(git log *)",
    "Bash(git diff *)",
    "Read"
  ],
  "permissionMode": "plan",
  "maxTurns": 50,
  "env": {
    "CUSTOM_VAR": "value"
  },
  "hooks": {
    "PreToolUse": ["check-schema"],
    "PostToolUse": ["format-output"]
  }
}

MCP Configuration

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./server.js"],
      "env": {
        "API_KEY": "key"
      }
    }
  }
}

Exit Codes

Examples:

claude auth status
echo $?  # Returns 0 if logged in, 1 if not

Common Error Handling

Installation

Authentication

Performance

Configuration

Debugging and Diagnostics

Doctor Command

claude /doctor

Checks:

• Installation type, version, search functionality
• Auto-update status and available versions
• Invalid settings files (malformed JSON, wrong types)
• MCP server configuration errors
• Keybinding configuration issues
• Context usage warnings (large CLAUDE.md, high MCP tokens)
• Plugin and agent loading errors

Verbose Output

claude --verbose

Shows:

• Complete turn-by-turn output
• Tool invocations and results
• Token usage per turn
• API request/response details

Debug Categories

claude --debug "api,mcp"
claude --debug "!statsig,!file"  # Everything EXCEPT statsig, file

macOS Terminal Configuration (For Alt-Keys)

If Alt+B, Alt+F, Alt+Y, Alt+M, Alt+P don't work, configure Option as Meta:

iTerm2

1. Settings → Profiles → Keys
2. Set Left Option Key to "Esc+"
3. Set Right Option Key to "Esc+"

Terminal.app

1. Settings → Profiles → Keyboard
2. Check "Use Option as Meta Key"

VS Code Terminal

1. Settings → Profiles → Keys
2. Set Left/Right Option Key to "Esc+"

Best Practices

Session Management

1. Use named sessions for better organization:

   Copy

   claude -n "feature-auth-refactor"
   

2. Continue instead of resume for same directory:

   Copy

   claude -c  # Instead of -r session-id
   

3. Worktrees for parallel work:

   Copy

   claude -w feature-1  # Isolated branch
   claude -w feature-2  # Different branch
   

Performance

1. Compact context regularly:

   Copy

   /compact
   

2. Scope large codebases with --add-dir:

   Copy

   claude --add-dir ./src ./tests
   

3. Limit turns when cost-sensitive:

   Copy

   claude -p --max-turns 3 "query"
   

Security

1. Never pass credentials in CLI flags:

   Copy

   # WRONG
   claude --betas "api_key=secret"
   
   # RIGHT
   export ANTHROPIC_API_KEY=sk-ant-...
   claude
   

2. Use print mode for sensitive work:

   Copy

   claude -p "query"  # No persistent session
   

3. Use permission modes:

   Copy

   claude --permission-mode plan  # Review before execution
   

Last Updated: March 2026 | Source: Anthropic Code Documentation

Sources and Links

• CLI Reference
• Interactive Mode
• npm Package
• Official Claude Code Documentation
• GitHub (Anthropic)
• Anthropic SDK Python
• Anthropic SDK TypeScript
• Claude Code Docs Index