Skip to content

cli-reference.md

Latest commit

 

History

History
130 lines (114 loc) · 50 KB

cli-reference.md

File metadata and controls

130 lines (114 loc) · 50 KB

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

CLI reference

Complete reference for Claude Code command-line interface, including commands and flags.

CLI commands

You can start sessions, pipe content, resume conversations, and manage updates with these commands:

Command Description Example
claude Start interactive session claude
claude "query" Start interactive session with initial prompt claude "explain this project"
claude -p "query" Query via SDK, then exit claude -p "explain this function"
cat file | claude -p "query" Process piped content cat logs.txt | claude -p "explain"
claude -c Continue most recent conversation in current directory claude -c
claude -c -p "query" Continue via SDK claude -c -p "Check for type errors"
claude -r "<session>" "query" Resume session by ID or name claude -r "auth-refactor" "Finish this PR"
claude update Update to latest version claude update
claude install [version] Install or reinstall the native binary. Accepts a version like 2.1.118, or stable or latest. See Install a specific version claude install stable
claude auth login Sign in to your Anthropic account. Use --email to pre-fill your email address, --sso to force SSO authentication, and --console to sign in with Anthropic Console for API usage billing instead of a Claude subscription claude auth login --console
claude auth logout Log out from your Anthropic account claude auth logout
claude auth status Show authentication status as JSON. Use --text for human-readable output. Exits with code 0 if logged in, 1 if not claude auth status
claude agents List all configured subagents, grouped by source claude agents
claude auto-mode defaults Print the built-in auto mode classifier rules as JSON. Use claude auto-mode config to see your effective config with settings applied claude auto-mode defaults > rules.json
claude mcp Configure Model Context Protocol (MCP) servers See the Claude Code MCP documentation.
claude plugin Manage Claude Code plugins. Alias: claude plugins. See plugin reference for subcommands claude plugin install code-review@claude-plugins-official
claude project purge [path] Delete all local Claude Code state for a project: transcripts, task lists, debug logs, file-edit history, prompt history lines, and the project's entry in ~/.claude.json. Omit [path] to pick from an interactive list. Flags: --dry-run to preview, -y/--yes to skip confirmation, -i/--interactive to confirm each item, --all for every project. See Clear local data claude project purge ~/work/repo --dry-run
claude remote-control Start a Remote Control server to control Claude Code from Claude.ai or the Claude app. Runs in server mode (no local interactive session). See Server mode flags claude remote-control --name "My Project"
claude setup-token Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it. Requires a Claude subscription. See Generate a long-lived token claude setup-token
claude ultrareview [target] Run ultrareview non-interactively. Prints findings to stdout and exits 0 on success or 1 on failure. Use --json for the raw payload and --timeout <minutes> to override the 30-minute default claude ultrareview 1234 --json

If you mistype a subcommand, Claude Code suggests the closest match and exits without starting a session. For example, claude udpate prints Did you mean claude update?.

CLI flags

Customize Claude Code's behavior with these command-line flags. claude --help does not list every flag, so a flag's absence from --help does not mean it is unavailable.

Flag Description Example
--add-dir Add additional working directories for Claude to read and edit files. Grants file access; most .claude/ configuration is not discovered from these directories. Validates each path exists as a directory. To persist these directories across sessions, set permissions.additionalDirectories in settings claude --add-dir ../apps ../lib
--agent Specify an agent for the current session (overrides the agent setting) claude --agent my-custom-agent
--agents Define custom subagents dynamically via JSON. Uses the same field names as subagent frontmatter, plus a prompt field for the agent's instructions claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'
--allow-dangerously-skip-permissions Add bypassPermissions to the Shift+Tab mode cycle without starting in it. Lets you begin in a different mode like plan and switch to bypassPermissions later. See permission modes claude --permission-mode plan --allow-dangerously-skip-permissions
--allowedTools Tools that execute without prompting for permission. See permission rule syntax for pattern matching. To restrict which tools are available, use --tools instead "Bash(git log *)" "Bash(git diff *)" "Read"
--append-system-prompt Append custom text to the end of the default system prompt claude --append-system-prompt "Always use TypeScript"
--append-system-prompt-file Load additional system prompt text from a file and append to the default prompt claude --append-system-prompt-file ./extra-rules.txt
--bare Minimal mode: skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster. Claude has access to Bash, file read, and file edit tools. Sets CLAUDE_CODE_SIMPLE. See bare mode claude --bare -p "query"
--betas Beta headers to include in API requests (API key users only) claude --betas interleaved-thinking
--channels (Research preview) MCP servers whose channel notifications Claude should listen for in this session. Space-separated list of plugin:<name>@<marketplace> entries. Requires Claude.ai authentication claude --channels plugin:my-notifier@my-marketplace
--chrome Enable Chrome browser integration for web automation and testing claude --chrome
--continue, -c Load the most recent conversation in the current directory. Includes sessions that added this directory with /add-dir claude --continue
--dangerously-load-development-channels Enable channels that are not on the approved allowlist, for local development. Accepts plugin:<name>@<marketplace> and server:<name> entries. Prompts for confirmation claude --dangerously-load-development-channels server:webhook
--dangerously-skip-permissions Skip permission prompts. Equivalent to --permission-mode bypassPermissions. See permission modes for what this does and does not skip claude --dangerously-skip-permissions
--debug Enable debug mode with optional category filtering (for example, "api,hooks" or "!statsig,!file") claude --debug "api,mcp"
--debug-file <path> Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over CLAUDE_CODE_DEBUG_LOGS_DIR claude --debug-file /tmp/claude-debug.log
--disable-slash-commands Disable all skills and commands for this session claude --disable-slash-commands
--disallowedTools Tools that are removed from the model's context and cannot be used "Bash(git log *)" "Bash(git diff *)" "Edit"
--effort Set the effort level for the current session. Options: low, medium, high, xhigh, max; available levels depend on the model. Overrides the effortLevel setting for this session and does not persist claude --effort high
--enable-auto-mode {/* max-version: 2.1.110 */}Removed in v2.1.111. Auto mode is now in the Shift+Tab cycle by default; use --permission-mode auto to start in it claude --permission-mode auto
--exclude-dynamic-system-prompt-sections Move per-machine sections from the system prompt (working directory, environment info, memory paths, git status) into the first user message. Improves prompt-cache reuse across different users and machines running the same task. Only applies with the default system prompt; ignored when --system-prompt or --system-prompt-file is set. Use with -p for scripted, multi-user workloads claude -p --exclude-dynamic-system-prompt-sections "query"
--fallback-model Enable automatic fallback to specified model when default model is overloaded (print mode only) claude -p --fallback-model sonnet "query"
--fork-session When resuming, create a new session ID instead of reusing the original (use with --resume or --continue) claude --resume abc123 --fork-session
--from-pr Resume sessions linked to a specific pull request. Accepts a PR number, a GitHub or GitHub Enterprise PR URL, a GitLab merge request URL, or a Bitbucket pull request URL. Sessions are linked automatically when Claude creates the pull request claude --from-pr 123
--ide Automatically connect to IDE on startup if exactly one valid IDE is available claude --ide
--init Run Setup hooks with the init matcher before the session (print mode only) claude -p --init "query"
--init-only Run Setup and SessionStart hooks, then exit without starting a conversation claude --init-only
--include-hook-events Include all hook lifecycle events in the output stream. Requires --output-format stream-json claude -p --output-format stream-json --include-hook-events "query"
--include-partial-messages Include partial streaming events in output. Requires --print and --output-format stream-json claude -p --output-format stream-json --include-partial-messages "query"
--input-format Specify input format for print mode (options: text, stream-json) claude -p --output-format json --input-format stream-json
--json-schema Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see structured outputs) claude -p --json-schema '{"type":"object","properties":{...}}' "query"
--maintenance Run Setup hooks with the maintenance matcher before the session (print mode only) claude -p --maintenance "query"
--max-budget-usd Maximum dollar amount to spend on API calls before stopping (print mode only) claude -p --max-budget-usd 5.00 "query"
--max-turns Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default claude -p --max-turns 3 "query"
--mcp-config Load MCP servers from JSON files or strings (space-separated) claude --mcp-config ./mcp.json
--model Sets the model for the current session with an alias for the latest model (sonnet or opus) or a model's full name. Overrides the model setting and ANTHROPIC_MODEL claude --model claude-sonnet-4-6
--name, -n Set a display name for the session, shown in /resume and the terminal title. You can resume a named session with claude --resume <name>.

/rename changes the name mid-session and also shows it on the prompt bar		 claude -n "my-feature-work"
--no-chrome Disable Chrome browser integration for this session claude --no-chrome
--no-session-persistence Disable session persistence so sessions are not saved to disk and cannot be resumed. Print mode only. The CLAUDE_CODE_SKIP_PROMPT_HISTORY environment variable does the same in any mode claude -p --no-session-persistence "query"
--output-format Specify output format for print mode (options: text, json, stream-json) claude -p "query" --output-format json
--permission-mode Begin in a specified permission mode. Accepts default, acceptEdits, plan, auto, dontAsk, or bypassPermissions. Overrides defaultMode from settings files claude --permission-mode plan
--permission-prompt-tool Specify an MCP tool to handle permission prompts in non-interactive mode claude -p --permission-prompt-tool mcp_auth_tool "query"
--plugin-dir Load a plugin from a directory or .zip archive for this session only. Each flag takes one path. Repeat the flag for multiple plugins: --plugin-dir A --plugin-dir B.zip claude --plugin-dir ./my-plugin
--plugin-url Fetch a plugin .zip archive from a URL for this session only. Each flag takes one URL. Repeat the flag for multiple plugins claude --plugin-url https://example.com/plugin.zip
--print, -p Print response without interactive mode (see Agent SDK documentation for programmatic usage details) claude -p "query"
--remote Create a new web session on claude.ai with the provided task description claude --remote "Fix the login bug"
--remote-control, --rc Start an interactive session with Remote Control enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session claude --remote-control "My Project"
--remote-control-session-name-prefix <prefix> Prefix for auto-generated Remote Control session names when no explicit name is set. Defaults to your machine's hostname, producing names like myhost-graceful-unicorn. Set CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX for the same effect claude remote-control --remote-control-session-name-prefix dev-box
--replay-user-messages Re-emit user messages from stdin back on stdout for acknowledgment. Requires --input-format stream-json and --output-format stream-json claude -p --input-format stream-json --output-format stream-json --replay-user-messages
--resume, -r Resume a specific session by ID or name, or show an interactive picker to choose a session. Includes sessions that added this directory with /add-dir claude --resume auth-refactor
--session-id Use a specific session ID for the conversation (must be a valid UUID) claude --session-id "550e8400-e29b-41d4-a716-446655440000"
--setting-sources Comma-separated list of setting sources to load (user, project, local) claude --setting-sources user,project
--settings Path to a settings JSON file or an inline JSON string. Values you set here override the same keys in your settings.json files for this session. Keys you omit keep their file-based values. See settings precedence claude --settings ./settings.json
--strict-mcp-config Only use MCP servers from --mcp-config, ignoring all other MCP configurations claude --strict-mcp-config --mcp-config ./mcp.json
--system-prompt Replace the entire system prompt with custom text claude --system-prompt "You are a Python expert"
--system-prompt-file Load system prompt from a file, replacing the default prompt claude --system-prompt-file ./custom-prompt.txt
--teleport Resume a web session in your local terminal claude --teleport
--teammate-mode Set how agent team teammates display: auto (default), in-process, or tmux. Overrides the teammateMode setting for this session. See Choose a display mode claude --teammate-mode in-process
--tmux Create a tmux session for the worktree. Requires --worktree. Uses iTerm2 native panes when available; pass --tmux=classic for traditional tmux claude -w feature-auth --tmux
--tools Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read" claude --tools "Bash,Edit,Read"
--verbose Enable verbose logging, shows full turn-by-turn output. Overrides the viewMode setting for this session claude --verbose
--version, -v Output the version number claude -v
--worktree, -w Start Claude in an isolated git worktree at <repo>/.claude/worktrees/<name>. If no name is given, one is auto-generated claude -w feature-auth

System prompt flags

Claude Code provides four flags for customizing the system prompt. All four work in both interactive and non-interactive modes.

Flag Behavior Example
--system-prompt Replaces the entire default prompt claude --system-prompt "You are a Python expert"
--system-prompt-file Replaces with file contents claude --system-prompt-file ./prompts/review.txt
--append-system-prompt Appends to the default prompt claude --append-system-prompt "Always use TypeScript"
--append-system-prompt-file Appends file contents to the default prompt claude --append-system-prompt-file ./style-rules.txt

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

For most use cases, use an append flag. Appending preserves Claude Code's built-in capabilities while adding your requirements. Use a replacement flag only when you need complete control over the system prompt.

See also