Title: CLI reference - Claude Code Docs
URL Source: https://docs.claude.com/en/docs/claude-code/cli-reference
Markdown Content:
English
Search...
⌘K Ask AI
Search...
Navigation
Reference
CLI reference
Getting startedBuild with Claude CodeDeploymentAdministrationConfigurationReferenceAgent SDKWhat's NewResources
- CLI reference
- Commands
- Environment variables
- Tools reference
- Interactive mode
- Checkpointing
- Hooks reference
- Plugins reference
- Channels reference
On this page
Reference
Copy page
Complete reference for Claude Code command-line interface, including commands and flags.
Copy page
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 |
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 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 |
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 |
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. Session-scoped and does not persist to settings |
claude --effort high |
--enable-auto-mode |
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 initialization hooks and start interactive mode | claude --init |
--init-only |
Run initialization hooks and exit (no interactive session) | 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 maintenance hooks and start interactive mode | claude --maintenance |
--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 |
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) | 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 plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: --plugin-dir A --plugin-dir B |
claude --plugin-dir ./my-plugins |
--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 a JSON string to load additional settings from | 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. 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 | 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
- Chrome extension - Browser automation and web testing
- Interactive mode - Shortcuts, input modes, and interactive features
- Quickstart guide - Getting started with Claude Code
- Common workflows - Advanced workflows and patterns
- Settings - Configuration options
- Agent SDK documentation - Programmatic usage and integrations
Was this page helpful?
Yes No
⌘I
Company
AnthropicCareersEconomic FuturesResearchNewsTrust centerTransparency
Help and security
AvailabilityStatusSupport center
Learn
CoursesMCP connectorsCustomer storiesEngineering blogEventsPowered by ClaudeService partnersStartups program
Terms and policies
Privacy choicesPrivacy policyDisclosure policyUsage policyCommercial termsConsumer terms
Assistant
Responses are generated using AI and may contain mistakes.