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

References

Anthropic. "CLI reference." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/cli-reference
Anthropic. Claude Code 2.1.259, built-in claude --help output. Distributed in the release package published September 2, 2026. Package metadata: https://registry.npmjs.org/%40anthropic-ai%2Fclaude-code/2.1.259
Anthropic. "Manage sessions." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/sessions
Anthropic. "Run Claude Code programmatically." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/headless
Anthropic. "Choose a permission mode." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/permission-modes
Anthropic. "Run parallel sessions with worktrees." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/worktrees
Anthropic. "Connect Claude Code to tools via MCP." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/mcp
Anthropic. "Create custom subagents." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/sub-agents
Anthropic. "Manage multiple agents with agent view." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/agent-view
Anthropic. "Continue local sessions from any device with Remote Control." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/remote-control
Anthropic. "Use Claude Code on the web." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/claude-code-on-the-web
Anthropic. "Claude Code changelog." Claude Code documentation. Version 2.1.111 release entry. Accessed September 2, 2026. https://code.claude.com/docs/en/changelog
Anthropic. "Error reference." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/errors
Anthropic. "Use Claude Code with Chrome." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/chrome
Anthropic. "Create plugins." Claude Code documentation. Accessed September 2, 2026. https://code.claude.com/docs/en/plugins
Anthropic. "v2.1.259." Claude Code GitHub releases. September 2, 2026. https://github.com/anthropics/claude-code/releases/tag/v2.1.259

Editing: Claude Code CLI Flags