Claude Code CLI Flags
Claude Code CLI Flags are command-line options passed to the top-level claude command to choose a session, model, permission policy, output format, integration, or startup behavior. This page covers every top-level flag in Anthropic's published Claude Code CLI reference as checked on September 2, 2026, then reconciles that list with the built-in help in Claude Code 2.1.259.[1][2]
The ordering below is an editorial usefulness guide for a typical developer, not an Anthropic ranking or a measurement of usage. Broad, frequently useful options come first. Accessibility and deployment-specific flags appear later only because fewer users need them, not because they are less important to those users. Use Ctrl+F or Cmd+F to jump directly to a flag.
This scope is the top-level form claude [options] [prompt]. It does not try to merge in options that belong only to subcommands such as claude mcp add or claude plugin install, and it does not include in-session slash commands such as /model or /resume. Anthropic explicitly notes that claude --help is not exhaustive, so absence from the terminal help does not by itself mean a documented flag is unsupported.[1] The reconciled inventory contains 80 current entries with aliases grouped, plus one removed flag retained for historical lookup.[1][2]
The 13 flags most people need
These are the best starting points for ordinary interactive work, session recovery, and simple scripts.[1][3][4][5][6]
| Rank | Flag | What it is for | Example |
|---|---|---|---|
| 1 | --continue, -c | Continue the most recent eligible conversation associated with the current directory. Selection differs in interactive and print modes. | claude -c |
| 2 | --resume [value], -r [value] | Resume by session ID or name, search the picker, or open the picker with no value. | claude -r auth-refactor |
| 3 | --permission-mode <mode> | Start in default or manual, acceptEdits, plan, auto, dontAsk, or bypassPermissions, subject to availability and policy. | claude --permission-mode plan |
| 4 | --model <alias-or-id> | Choose the model for this launch with an alias or full model ID. | claude --model sonnet |
| 5 | --effort <level> | Set the session's reasoning effort without changing saved settings. The web reference lists low, medium, high, xhigh, max, and ultracode; model support varies, and 2.1.259 help omits ultracode from its summary. | claude --effort high |
| 6 | --worktree [name], -w [name] | Start in an isolated git worktree; a name is optional. Current versions can also accept supported pull-request or merge-request forms. | claude -w feature-auth |
| 7 | --print, -p | Run non-interactively, print the response, and exit. Useful for pipes, scripts, and CI. | claude -p "Explain this repository" |
| 8 | --name <name>, -n <name> | Give the session a display name that can later be used with --resume. | claude -n auth-refactor |
| 9 | --add-dir <directories...> | Grant access to additional working directories for this launch. | claude --add-dir ../shared ../docs |
| 10 | --from-pr [value] | Filter the session picker to conversations linked to a pull request or merge request. | claude --from-pr 123 |
| 11 | --fork-session | Copy the selected conversation to a new session ID when used with --continue or --resume. | claude -r auth-refactor --fork-session |
| 12 | --version, -v | Print the installed Claude Code version and exit. | claude -v |
| 13 | --help, -h | Print the built-in help for the current binary. It is useful, but not exhaustive. | claude --help |
The detailed selection rules for the first two entries are covered separately in claude --continue and claude --resume. In particular, --continue chooses by recency and directory, whereas --resume can target a specific ID or name.[3]
Copy-paste recipes
These examples combine documented top-level options for sessions, permissions, worktrees, print mode, and MCP configuration.[1][3][4][5][6][7]
# Reopen recent work in this directory
claude --continue
# Branch from a named session without changing the original transcript
claude --resume auth-refactor --fork-session
# Explore before allowing edits
claude --permission-mode plan
# Use an isolated worktree
claude --worktree feature-auth
# Get one JSON result for a script
claude -p "Summarize this repository" --output-format json
# Run a bounded review with read-only built-ins and no MCP tools
claude -p "Review this repository" \
--tools "Read,Grep,Glob" \
--disallowedTools "mcp__*" \
--permission-mode dontAsk \
--max-turns 5 \
--max-budget-usd 2.00
# Load only the MCP configuration supplied here
claude --mcp-config ./mcp.json --strict-mcp-config
# Diagnose whether a customization is breaking startup
claude --safe-mode
Non-interactive -p runs skip the workspace-trust dialog, so they should be launched only in trusted directories. Anthropic recommends --bare for reproducible scripts, but bare mode does not read Anthropic OAuth or keychain credentials; it needs ANTHROPIC_API_KEY or an apiKeyHelper passed through --settings. Third-party cloud providers keep their own credential paths.[4]
Common flags for automation, customization, and integrations
These options become useful when a workflow moves beyond an ordinary interactive session. Restrictions in this table are part of the flag's behavior, not optional recommendations.[1][4][5][7][8][9]
| Flag | Best use | Requirements or important limits | Example |
|---|---|---|---|
--allowedTools <rules...>, --allowed-tools <rules...> | Auto-approve matching tool calls | Does not restrict which tools exist; use --tools for that | claude -p "Check the logs" --allowedTools "Read" "Grep" |
--disallowedTools <rules...>, --disallowed-tools <rules...> | Deny tools or scoped actions | A bare tool name removes it; a scoped rule keeps the tool visible but blocks matches | claude --disallowedTools "Bash(rm *)" |
--tools <tools...> | Restrict the built-in tool set | Does not restrict MCP tools; use --disallowedTools "mcp__*" for those | claude --tools "Read,Grep,Glob" |
--output-format <format> | Choose text, json, or stream-json output | Print mode only | claude -p "List risks" --output-format json |
--json-schema <schema> | Require a validated structured result | Print mode only; the value must be a JSON Schema | claude -p "Extract names" --json-schema '{"type":"array","items":{"type":"string"}}' |
--max-budget-usd <amount> | Cap API spending for one run | Print mode only; subagent spending counts toward the cap | claude -p "Review the project" --max-budget-usd 2.00 |
--max-turns <integer> | Bound agentic turns | Print mode only; reaching the limit exits with an error | claude -p "Find the bug" --max-turns 5 |
--bare | Make scripts faster and more reproducible by skipping auto-discovered customizations | Anthropic auth must come from an API key or an apiKeyHelper supplied through --settings | claude --bare -p "Summarize README.md" --allowedTools "Read" |
--settings <path-or-json> | Supply extra settings for this launch | File must be regular and no larger than 2 MiB; supplied values override matching file-based values | claude --settings ./ci-settings.json |
--mcp-config <configs...> | Load Model Context Protocol servers from JSON files or strings | With -p, startup may wait for pending servers up to the MCP timeout | claude --mcp-config ./mcp.json |
--agent <name> | Start with one configured subagent definition | Overrides the saved agent setting | claude --agent reviewer |
--agents <json> | Define custom subagents inline | Invalid JSON causes startup to fail | claude --agents '{"reviewer":{"description":"Reviews code","prompt":"Review changes"}}' |
--append-system-prompt <text> | Add one-off instructions while retaining Claude Code's default prompt | Safer default than replacing the whole system prompt | claude --append-system-prompt "Use TypeScript" |
--append-system-prompt-file <path> | Append instructions loaded from a file | Works in interactive and print modes | claude --append-system-prompt-file ./review-rules.txt |
--autocompact <auto-or-tokens> | Override the auto-compaction window for this session | Accepts auto or a threshold from 100k through 1M tokens | claude --autocompact 500k |
--fallback-model <models> | Try fallback models if the primary is unavailable | The web reference documents interactive fallback chains, while 2.1.259 help still says print mode only | claude --fallback-model sonnet,haiku |
--chrome | Enable Claude in Chrome for browser automation | Requires the Chrome integration | claude --chrome |
--no-chrome | Disable the Chrome integration for this launch | Useful when Chrome is enabled in saved configuration | claude --no-chrome |
--ide | Connect automatically when exactly one valid IDE is available | Does nothing useful when the connection is ambiguous or unavailable | claude --ide |
--remote-control [name], --rc [name] | Start an interactive session controllable from claude.ai or the Claude app | For the claude remote-control subcommand, place its options after the subcommand | claude --remote-control "My Project" |
--bg, --background | Start a background agent and return immediately | Cannot be combined with -p; prints the ID used by attach, logs, stop, and rm | claude --bg "Investigate the flaky test" |
--cloud [description-or-session] | Create a cloud task or address an existing cloud session | A new task description conflicts with -p; an existing session ID or URL can use -p to queue a message | claude --cloud "Fix the login bug" |
--teleport [session] | Bring a Claude Code web session into the local terminal | Applies to eligible web sessions | claude --teleport |
--safe-mode | Troubleshoot startup with customizations disabled | Keeps normal authentication, built-in tools, model selection, permissions, and managed policy | claude --safe-mode |
--verbose | Show detailed turn-by-turn output | Overrides the saved view mode for this session | claude --verbose |
--allowedTools, --tools, and --disallowedTools sound similar but control different layers. The first skips prompts for matching actions. The second limits the built-in tools Claude receives. The third denies or removes named tools and is also the mechanism for excluding MCP tools. Combining them without understanding that distinction can make an automated run broader or narrower than intended.[1][5]
--safe-mode and --bare also solve different problems. Safe mode is a troubleshooting launch that preserves normal authentication and core behavior while disabling customizations. Bare mode is a minimal scripting environment that avoids discovered configuration and has stricter Anthropic-authentication rules.[1][4]
Specialized and conditional flags
The following flags are high-value in the right environment, but most users do not need them every day. They are alphabetical within this tier for faster lookup.[1][5][7][8][9][10][11][12][13][14][15]
| Flag | What it does | Requirement, scope, or warning |
|---|---|---|
--advisor <model> | Enables the server-side advisor tool with a model alias or full ID | Documented in the web reference but omitted from 2.1.259 top-level help; fable requires access |
--allow-dangerously-skip-permissions | Adds bypassPermissions to the interactive Shift+Tab cycle without starting in it | Makes the bypass mode selectable; it does not activate it |
--append-subagent-system-prompt <text> | Appends instructions to subagent system prompts, including nested subagents except conversation-forked ones | Print mode only |
--ax-screen-reader | Uses flat, screen-reader-friendly output without decorative borders or animations | Forces the classic renderer; attached background sessions still use fullscreen rendering |
--betas <headers...> | Adds beta headers to API requests | API-key users only |
--channels <entries...> | Listens for notifications from selected MCP channel servers | Research preview; requires supported Anthropic authentication |
--dangerously-load-development-channels <entries...> | Enables unapproved channel servers for local development | Prompts for confirmation; accepts documented plugin: and server: entries |
--dangerously-skip-permissions | Starts in bypassPermissions, skipping the normal permission layer | Anthropic recommends it only inside isolated containers or virtual machines without internet access |
--debug[=filter], -d[=filter] | Enables debug mode, optionally filtering categories | A filter binds in the --debug='mcp,startup' form; a space-separated value only enables debug mode |
--debug-file <path> | Writes debug logs to a chosen file | Implicitly enables debug mode |
--disable-slash-commands | Disables skills and commands for the session | Removes both custom and built-in slash-command access for that launch |
--environment <environment-id> | Creates a cloud session on a self-hosted environment | IDs begin with ccpool_; requires Claude Code 2.1.224 or later |
--exclude-dynamic-system-prompt-sections | Moves per-machine prompt sections into the first user message to improve cross-machine prompt-cache reuse | Ignored with --system-prompt or --system-prompt-file; aimed at scripted multi-user workloads |
--exec <shell-command> | Runs a PTY-backed shell command as a background job instead of a Claude conversation | Use with --bg |
--forward-subagent-text | Emits subagent text and thinking blocks into stream JSON with parent tool-use IDs | Requires -p --output-format stream-json; documented examples also use --verbose |
--init | Runs Setup hooks whose matcher is init before the conversation | Print mode only |
--init-only | Runs Setup and SessionStart hooks, then exits | Starts no conversation |
--include-hook-events | Adds hook lifecycle events to stream output | Requires --output-format stream-json; not every lifecycle event produces every event type |
--include-partial-messages | Emits partial message chunks as they arrive | Requires -p --output-format stream-json |
--input-format <format> | Chooses text or realtime stream-json input | Print mode only |
--maintenance | Runs Setup hooks whose matcher is maintenance before the conversation | Print mode only |
--no-session-persistence | Prevents the run from being saved to disk or resumed | Print mode only |
--permission-prompt-tool <mcp-tool> | Sends non-interactive permission requests to a specified MCP tool | The tool and its server must be available; interaction-required MCP tools cannot approve themselves |
--plugin-dir <path> | Loads a plugin directory or .zip for this session only | Repeat the flag for multiple plugins |
--plugin-url <url> | Downloads a plugin .zip for this session only | Repeat the flag or use the documented multi-URL form; remote code should be trusted before loading |
--prompt-suggestions [boolean] | Emits a predicted next-prompt event after eligible turns | Requires -p, stream-json, and --verbose; short conversations may emit none |
--ref <branch> | Bases a self-hosted cloud checkout on a named ref instead of local HEAD | Only with --environment |
--remote-control-session-name-prefix <prefix> | Changes the prefix used for automatically generated Remote Control session names | Defaults to the hostname when no explicit name is supplied |
--replay-user-messages | Re-emits streaming-input user messages on stdout as acknowledgments | Requires both input and output format to be stream-json |
--restricted | Creates a constrained evaluation-oriented environment with limited tools, settings, and filesystem reach | Refuses bypassPermissions and cloud-session creation; requires 2.1.248 or later |
--session-id <uuid> | Assigns a specific UUID to a new conversation | Value must be a valid UUID |
--setting-sources <sources> | Selects any of user, project, and local settings sources | Comma-separated; does not name managed settings |
--strict-mcp-config | Ignores ordinary MCP configurations and uses only --mcp-config entries | Pair with --mcp-config; managed MCP policy can still affect behavior |
--system-prompt <text> | Replaces Claude Code's entire default system prompt | Drops the default tool guidance, safety instructions, and coding conventions |
--system-prompt-file <path> | Replaces the default system prompt with file contents | Mutually exclusive with --system-prompt |
--teammate-mode <mode> | Chooses how agent-team teammates display: in-process, auto, tmux, or iterm2 | Applies to agent teams and overrides the saved setting for this launch |
--tmux[=classic] | Opens the worktree session in tmux, using iTerm2 panes when available | Requires --worktree; --tmux=classic forces traditional tmux |
The two replacement prompt flags are mutually exclusive. Either replacement form may be combined with --append-system-prompt or --append-system-prompt-file. Appending keeps Claude Code's default identity and operating guidance; replacing makes the caller responsible for supplying anything still needed.[1]
Restricted mode is not a synonym for plan mode. Plan mode is a read-and-analyze workflow with normal settings and integrations. Restricted mode is intended for harnesses on shared machines: it ignores user, project, and local settings, confines file tools to working directories, removes code-running tools and WebFetch unless individually named, and refuses bypass mode and cloud-session creation.[1][5]
Flags visible in Claude Code 2.1.259 help but not yet in the web table
In addition to --help itself, the 2.1.259 binary published on September 2, 2026 exposes the following four flags in claude --help, although they were absent from the web reference's flag table when this article was checked. They are listed separately because built-in help is version-specific and their public documentation may change. Anthropic's source changelog independently records the --permission-prompts none behavior in the 2.1.259 release entry.[1][2][16]
| Flag | Built-in help description | Compatibility note |
|---|---|---|
--brief | Enables the SendUserMessage tool for agent-to-user communication | Treat as version-specific until Anthropic documents it in the web reference |
--file <specs...> | Downloads file resources at startup using file_id:relative_path specifications | A relative destination is required for each file ID |
--permission-prompts <host-or-none> | Chooses who answers permission prompts in print mode | host is the default; none automatically denies actions that would require a prompt, while the active permission mode still decides everything else |
--system-prompt-snapshot <on-or-off> | Records one system prompt per conversation and reuses it on later requests and resumes | Custom system-prompt flags turn the default off; a saved snapshot can cause a later replacement value to be ignored until compaction; it has no effect where prompt recording is not enabled |
--permission-prompts and the documented --permission-prompt-tool are not interchangeable labels. The former chooses between the host and automatic denial in 2.1.259 print mode. The latter names a particular MCP tool that handles non-interactive approval requests.[1][2]
Deprecated and removed flags
| Flag | Status | Use instead |
|---|---|---|
--remote [description-or-session] | Deprecated alias that still maps to --cloud | --cloud |
--enable-auto-mode | Removed in Claude Code 2.1.111 | --permission-mode auto |
These entries remain here so searches for old scripts lead to the current spelling rather than suggesting that the old behavior is still recommended.[1][12]
Important combinations and conflicts
| Combination | Result |
|---|---|
--continue --fork-session or --resume ... --fork-session | Selects an existing conversation but writes future turns under a new session ID.[1][3] |
--bg --resume <id> | Continues a stopped background session under the same ID; if it is already running, current help says Claude Code starts a copy and reports that fact.[2][9] |
--bg -p | Rejected; background mode and print mode cannot be combined.[1][13] |
--worktree --tmux | Creates the worktree and opens the session in tmux or an available iTerm2 pane.[1][6] |
--mcp-config ... --strict-mcp-config | Uses the explicitly supplied MCP configuration instead of ordinary configured servers, subject to managed policy.[1][7] |
--system-prompt with --system-prompt-file | Rejected because both replace the prompt.[1] |
| Either replacement prompt flag with either append flag | Allowed; replacement establishes the base and append adds more text.[1] |
--environment ... --ref <branch> | Starts the self-hosted cloud checkout from the named ref.[1] |
--input-format stream-json --output-format stream-json --replay-user-messages | Creates a bidirectional streaming protocol with user-message acknowledgments.[1][4] |
For Remote Control server mode, option placement matters. Anthropic documents that restrictive global flags written before the remote-control subcommand do not carry into the sessions it starts and can cause the server to refuse startup. Pass that subcommand's supported options after claude remote-control.[10][13]
How to check a particular installation
The web reference is the source for documented flags, while the installed executable is the source for what its own help chooses to expose. A practical version check is:[1][2]
claude --version
claude --help
claude <subcommand> --help
Some flags depend on a minimum version, account entitlement, administrator policy, authentication method, operating system, terminal, or rollout. A script intended for several machines should pin or check the Claude Code version and test required flags rather than assume that matching documentation dates imply identical binaries.[1][2][12]
See also
- Claude Code
- Claude --continue
- Claude --resume
- Claude --dangerously-skip-permissions
- Claude Code Subagents
- Claude Agent SDK
- Model Context Protocol
References
- ^Anthropic. "CLI reference." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...cli-reference
- ^Anthropic. Claude Code 2.1.259, built-in `claude --help` output. Distributed in the release package published September 2, 2026. Package metadata: registry.npmjs.org/...2.1.259
- ^Anthropic. "Manage sessions." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...sessions
- ^Anthropic. "Run Claude Code programmatically." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...headless
- ^Anthropic. "Choose a permission mode." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...permission-modes
- ^Anthropic. "Run parallel sessions with worktrees." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...worktrees
- ^Anthropic. "Connect Claude Code to tools via MCP." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...mcp
- ^Anthropic. "Create custom subagents." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...sub-agents
- ^Anthropic. "Manage multiple agents with agent view." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...agent-view
- ^Anthropic. "Continue local sessions from any device with Remote Control." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...remote-control
- ^Anthropic. "Use Claude Code on the web." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...claude-code-on-the-web
- ^Anthropic. "Claude Code changelog." Claude Code documentation. Version 2.1.111 release entry. Accessed September 2, 2026. code.claude.com/...changelog
- ^Anthropic. "Error reference." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...errors
- ^Anthropic. "Use Claude Code with Chrome." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...chrome
- ^Anthropic. "Create plugins." Claude Code documentation. Accessed September 2, 2026. code.claude.com/...plugins
- ^Anthropic. "v2.1.259." Claude Code GitHub releases. September 2, 2026. github.com/...v2.1.259
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation. Every suggestion is reviewed for sourcing before it goes live.
v1 · 3,525 words · full history
Fact-checks are independent of edits: a reviewer re-verifies the article against its sources and stamps the date. How we verify
Research and drafting on this wiki are AI-assisted, under named human editorial standards. How AI is used here
Reviewer note: Independently checked against current first-party Claude Code documentation and Claude Code 2.1.259 built-in help on September 2, 2026.
Cite this page: AI Wiki. "Claude Code CLI Flags." aiwiki.ai, updated 2 Sept 2026, fact-checked 2 Sept 2026. CC BY 4.0. https://aiwiki.ai/wiki/claude_code_cli_flags