All Flags

A flag changes how one claude run behaves. claude --help shows 66 flags. Another 64 work but stay hidden from the help text. This page lists both kinds in one place, grouped by what they do.

Pass a flag after claude, for example claude --model opus. Most flags last for one run only. A flag is on when you pass it. Some flags have a --no- twin, such as --no-chrome.

How to Read the Tables

• Documented: An official docs page names this item.
  means an official docs page names the flag, for example CLI Reference. The column In --help says whether the help text shows it.
• Undocumented: Only the program shows this item. It can change without notice.
  means only the program has it. It can change or vanish in any release. Treat these flags as unstable.
• Hidden flags mostly serve the Agent SDK, the desktop app, IDE extensions, and teammate processes.

Example

# One answer, JSON out, with a spend cap
claude -p "Summarize README.md" --output-format json --max-budget-usd 1

# A careful planning session on a chosen model
claude --model opus --effort high --permission-mode plan

# Stop after three agent turns
claude -p --max-turns 3 "Fix the failing test"

Flags by Job

Start and Print Mode

Flags that choose how a run starts and how print mode reads input and writes output.

Flag	Status	In --help	What it does
-p, --print	Documented: An official docs page names this item.	✅	Prints the answer and exits. This suits pipes. This mode skips the trust dialog.
--output-format <format>	Documented: An official docs page names this item.	✅	Sets the output of print mode to text, json, or stream-json. text is the default. json gives one result object. stream-json gives one JSON object per line, live.
--input-format <format>	Documented: An official docs page names this item.	✅	Sets the input of print mode to text or stream-json. text is the default. stream-json gives live input and control requests.
--json-schema <schema>	Documented: An official docs page names this item.	✅	Checks the final answer against a JSON Schema. It works only with --print. Pass the schema as a JSON string.
--include-hook-events	Documented: An official docs page names this item.	✅	Adds the hook events to the stream, with --output-format=stream-json.
--include-partial-messages	Documented: An official docs page names this item.	✅	Adds partial message chunks to the stream, with --print and stream-json. Adds stream_event lines.
--forward-subagent-text	Documented: An official docs page names this item.	✅	Adds the text of subagents to the stream as assistant and user messages, with --print and stream-json. Messages carry parent_tool_use_id.
--replay-user-messages	Documented: An official docs page names this item.	✅	Sends the user messages from stdin back on stdout as an acknowledgment. Needs both stream-json formats.
--max-budget-usd <amount>	Documented: An official docs page names this item.	✅	Stops at a spend limit in dollars, with --print only.
--max-turns <turns>	Documented: An official docs page names this item.	❌	Stops after a number of agent turns, with --print only.
--no-session-persistence	Documented: An official docs page names this item.	✅	Saves nothing to disk, so the session cannot be resumed, with --print only.
--prompt-suggestions [value]	Documented: An official docs page names this item.	✅	Turns on prompt suggestions. Print mode sends a prompt_suggestion message after each turn.
--init	Documented: An official docs page names this item.	❌	Runs Setup hooks with the init trigger and then goes on.
--init-only	Documented: An official docs page names this item.	❌	Runs Setup and SessionStart:startup hooks and then exits.
--maintenance	Documented: An official docs page names this item.	❌	Runs Setup hooks with the maintenance trigger and then goes on.
--session-mirror	Undocumented: Only the program shows this item. It can change without notice.	❌	Writes transcript_mirror frames to stdout, for the SDK.
--await-claim	Undocumented: Only the program shows this item. It can change without notice.	❌	Starts as a spare process for an SDK host and waits for a claim_session request.
--await-initialize	Undocumented: Only the program shows this item. It can change without notice.	❌	Reads the initialize request from stdin at startup so its fields apply like flags.
--sdk-url <url>	Undocumented: Only the program shows this item. It can change without notice.	❌	Uses a WebSocket endpoint for SDK input and output, with -p and stream-json.
--enable-auth-status	Undocumented: Only the program shows this item. It can change without notice.	❌	Turns on auth status messages in SDK mode.
--workload <tag>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets a workload tag for the attribution block, with --print only.
--client-data-url <url>	Undocumented: Only the program shows this item. It can change without notice.	❌	Loads a signed configuration document from a URL and exits if it fails.
--allow-other-models	Undocumented: Only the program shows this item. It can change without notice.	❌	With --client-data-url, starts on a model that the document does not list.
--managed-settings <json>	Undocumented: Only the program shows this item. It can change without notice.	❌	Gives policy settings as JSON from a parent process, for the SDK.
--host-auth-is-org-sign-in	Undocumented: Only the program shows this item. It can change without notice.	❌	Says that the token of the host is an organization sign-in, for desktop hosts.

Safe Modes, Settings, and Debug

Flags that strip your setup down, load extra settings, or turn on logs.

Flag	Status	In --help	What it does
-h, --help	Documented: An official docs page names this item.	✅	Shows the help text and exits.
-v, --version	Documented: An official docs page names this item.	✅	Prints the version number.
-d, --debug [filter]	Documented: An official docs page names this item.	✅	Turns on debug logs. An optional filter picks the categories, such as --debug=hooks,mcp or --debug='!hooks,!mcp'.
-d2e, --debug-to-stderr	Undocumented: Only the program shows this item. It can change without notice.	❌	Turns on debug mode and writes to stderr. The flag is deprecated.
--debug-file <path>	Documented: An official docs page names this item.	✅	Writes the debug logs to a file and turns on debug mode.
--verbose	Documented: An official docs page names this item.	✅	Overrides the verbose setting of your config.
--bare	Documented: An official docs page names this item.	✅	Starts with a minimal setup that has no hooks, no plugin sync, no auto memory, and no background work. It skips hooks, LSP, plugin sync, attribution, auto memory, background prefetches, keychain reads, and CLAUDE.md discovery.
--safe-mode	Documented: An official docs page names this item.	✅	Starts with all customizations off, such as CLAUDE.md, skills, plugins, hooks, and MCP servers.
--restricted	Documented: An official docs page names this item.	✅	Removes the tools that run code and WebFetch. Also ignores user, project, and local settings. It suits untrusted input.
--ax-screen-reader	Documented: An official docs page names this item.	✅	Draws flat text with no borders or animations, for screen readers.
--settings <file-or-json>	Documented: An official docs page names this item.	✅	Loads more settings from a JSON file or a JSON string.
--setting-sources <sources>	Documented: An official docs page names this item.	✅	Chooses which setting sources load: user, project, and local.
--project-config-root <dir>	Undocumented: Only the program shows this item. It can change without notice.	❌	Reads project settings and the .claude trees from another folder.

Permissions and Tools

Flags that set the permission mode and the tools the model may use. See Permissions.

Flag	Status	In --help	What it does
--permission-mode <mode>	Documented: An official docs page names this item.	✅	Sets the permission mode of the session.
--inherit-permission-mode <mode>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets a permission mode from a parent session, used only when nothing else sets one.
--dangerously-skip-permissions	Documented: An official docs page names this item. Caution: It deletes data, skips a safety check, or sends data off your machine. Skips all permission checks	✅	Skips all permission checks. Use it only in a sandbox with no internet access.
--allow-dangerously-skip-permissions	Documented: An official docs page names this item.	✅	Makes skipping all permission checks a choice, without turning it on.
--allowedTools, --allowed-tools <tools...>	Documented: An official docs page names this item.	✅	Lists the tools that run without a permission prompt.
--disallowedTools, --disallowed-tools <tools...>	Documented: An official docs page names this item.	✅	Lists the tools that the model cannot use.
--tools <tools...>	Documented: An official docs page names this item.	✅	Lists the built-in tools that the model can use. "default" uses the default set.
--permission-prompts <target>	Documented: An official docs page names this item.	✅	Sets who answers permission prompts: host or none. host means the SDK host or --permission-prompt-tool. none denies anything that would prompt. The permission mode decides the rest.
--permission-prompt-tool <tool>	Documented: An official docs page names this item.	❌	Names an MCP tool that answers permission prompts, with --print only.
--plan-mode-instructions <instructions>	Undocumented: Only the program shows this item. It can change without notice.	❌	Replaces the default steps of plan mode with your own text.
--enable-auto-mode	Undocumented: Only the program shows this item. It can change without notice. Deprecated: The program or the official docs call this deprecated. The help text says deprecated	❌	Opts in to auto mode. The flag is deprecated.

Model and Thinking

Flags that pick the model and set how hard it thinks.

Flag	Status	In --help	What it does
--model <model>	Documented: An official docs page names this item.	✅	Sets the model with an alias such as opus or with a full name.
--effort <level>	Documented: An official docs page names this item.	✅	Sets the effort level of the session.
--fallback-model <model>	Documented: An official docs page names this item.	✅	Sets one or more models to try when the main model is overloaded or unavailable.
--betas <betas...>	Documented: An official docs page names this item.	✅	Adds beta headers to API requests, for API key users only.
--advisor <model>	Documented: An official docs page names this item.	❌	Turns on the server-side advisor tool with the model that you name.
--thinking <mode>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the thinking mode: enabled (the same as adaptive) or disabled.
--thinking-display <display>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets how the thinking text appears in the response.
--max-thinking-tokens <tokens>	Undocumented: Only the program shows this item. It can change without notice. Deprecated: The program or the official docs call this deprecated. Use --thinking	❌	Sets a thinking token limit. The flag is deprecated. Use --thinking instead.
--task-budget <tokens>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets a task budget in tokens on the API side (output_config.task_budget).
--fast-mode <on|off>	Undocumented: Only the program shows this item. It can change without notice.	❌	Turns fast mode on or off.
--include-unsupported-models	Undocumented: Only the program shows this item. It can change without notice.	❌	Offers models that your account can use and this version does not know.
--autocompact <auto|tokens>	Documented: An official docs page names this item.	✅	Sets the auto-compact window to auto or to 100k to 1M tokens.

System Prompt

Flags that replace or extend the system prompt. See System Prompt.

Flag	Status	In --help	What it does
--system-prompt <prompt>	Documented: An official docs page names this item.	✅	Replaces the system prompt for the session.
--system-prompt-file <file>	Documented: An official docs page names this item.	❌	Reads the system prompt from a file.
--append-system-prompt <prompt>	Documented: An official docs page names this item.	✅	Adds text to the end of the default system prompt.
--append-system-prompt-file <file>	Documented: An official docs page names this item.	❌	Reads text from a file and adds it to the end of the default system prompt.
--append-subagent-system-prompt <prompt>	Documented: An official docs page names this item.	❌	Adds text to the system prompt of every subagent, with --print only.
--append-subagent-system-prompt-file <file>	Documented: An official docs page names this item.	❌	Reads text from a file and adds it to every subagent prompt, with --print only.
--system-prompt-snapshot <on|off>	Documented: An official docs page names this item.	✅	Sets whether Claude Code records the system prompt once and reuses it on every request and resume.
--exclude-dynamic-system-prompt-sections	Documented: An official docs page names this item.	✅	Moves the data of the machine from the system prompt to the first user message for better cache reuse.

Sessions and Worktrees

Flags that continue, fork, name, or rewind a session, or run it in a worktree or the background. See Sessions and Storage.

Flag	Status	In --help	What it does
-c, --continue	Documented: An official docs page names this item.	✅	Continues the newest conversation of the current folder.
-r, --resume [value]	Documented: An official docs page names this item.	✅	Resumes a conversation by session ID or name, or opens the picker.
--fork-session	Documented: An official docs page names this item.	✅	Creates a new session ID when you resume, with --resume or --continue.
--from-pr [value]	Documented: An official docs page names this item.	✅	Resumes a session that links to a pull request.
--session-id <uuid>	Documented: An official docs page names this item.	✅	Uses a UUID that you give as the session ID.
-n, --name <name>	Documented: An official docs page names this item.	✅	Sets the display name of the session.
--resume-session-at <message id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Resumes only up to one message of the chain, with --resume in print mode.
--resume-drops-turn <message id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Names the turn that a truncating resume drops. The resume fails if more would go.
--reply-on-resume	Undocumented: Only the program shows this item. It can change without notice.	❌	Asks the model to reply at once when the transcript ends with a user message.
--rewind-files <user-message-id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Restores the files to the state at a user message and exits. It needs --resume.
--bg, --background	Documented: An official docs page names this item.	✅	Starts the session in the background and prints its ID.
-w, --worktree [name]	Documented: An official docs page names this item.	✅	Creates a new git worktree for the session.
--tmux	Documented: An official docs page names this item.	✅	Creates a tmux session for the worktree. It needs --worktree.

Agents, Plugins, MCP, and Context

Flags that add agents, plugins, MCP servers, folders, and files.

Flag	Status	In --help	What it does
--agent <agent>	Documented: An official docs page names this item.	✅	Sets the agent of the session and overrides the agent setting.
--agents <json-or-file>	Documented: An official docs page names this item.	✅	Defines custom agents with JSON or a file.
--mcp-config <configs...>	Documented: An official docs page names this item.	✅	Loads MCP servers from JSON files or strings.
--strict-mcp-config	Documented: An official docs page names this item.	✅	Uses only the MCP servers from --mcp-config.
--plugin-dir <path>	Documented: An official docs page names this item.	✅	Loads a plugin from a folder or a .zip file for this session only.
--plugin-url <url>	Documented: An official docs page names this item.	✅	Fetches a plugin .zip file from a URL for this session only.
--plugin-dir-no-mcp <path>	Undocumented: Only the program shows this item. It can change without notice.	❌	Works like --plugin-dir but does not read the .mcp.json of the plugin.
--disable-slash-commands	Documented: An official docs page names this item.	✅	Turns off all skills and commands.
--add-dir <directories...>	Documented: An official docs page names this item.	✅	Gives the tools access to more folders.
--brief	Undocumented: Only the program shows this item. It can change without notice.	✅	Turns on the SendUserMessage tool so the agent can message the user.
--file <specs...>	Undocumented: Only the program shows this item. It can change without notice.	✅	Downloads file resources at startup, in the form file_id:relative_path.
--channels <servers...>	Documented: An official docs page names this item.	❌	Lists the MCP servers whose channel notifications may register this session.
--dangerously-load-development-channels <servers...>	Documented: An official docs page names this item. Caution: It deletes data, skips a safety check, or sends data off your machine.	❌	Loads channel servers that are not on the allowlist, for local development only.
--watch-artifact <artifact>	Undocumented: Only the program shows this item. It can change without notice.	❌	Watches a Claude artifact for new versions and comments.
--watch-artifact-no-autoreact <artifact>	Undocumented: Only the program shows this item. It can change without notice.	❌	Watches an artifact and does not react to it by itself.
--messaging-socket-path <path>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the socket or pipe path of the cross-session messaging server.
--proactivity <level>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the level of proactivity. The bundle gives no help text.

Teammate Flags

Flags that a lead agent passes to a teammate process it starts. You rarely set them by hand.

Flag	Status	In --help	What it does
--agent-id <id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the ID of a teammate agent.
--agent-name <name>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the display name of a teammate.
--team-name <name>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the team name for teammate coordination.
--agent-color <color>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets the UI color of a teammate.
--plan-mode-required	Undocumented: Only the program shows this item. It can change without notice.	❌	Requires plan mode before the teammate implements anything.
--teammate-mode <mode>	Documented: An official docs page names this item.	❌	Sets the mode of a teammate. The bundle gives no help text.
--agent-type <type>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets a custom agent type for a teammate.
--parent-session-id <id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Gives the parent session ID for analytics.

IDE, Desktop, and Deep Links

Flags that connect to an IDE, the desktop app, or a deep link.

Flag	Status	In --help	What it does
--ide	Documented: An official docs page names this item.	✅	Connects to the IDE at startup when exactly one valid IDE is open.
--desktop	Documented: An official docs page names this item.	✅	Opens the session in the Claude Desktop app instead of the terminal.
--chrome	Documented: An official docs page names this item.	✅	Turns on the Claude in Chrome integration.
--no-chrome	Documented: An official docs page names this item.	✅	Turns off the Claude in Chrome integration.
--prefill <text>	Undocumented: Only the program shows this item. It can change without notice.	❌	Fills the prompt box with text and does not send it.
--prefill-b64 <b64>	Undocumented: Only the program shows this item. It can change without notice.	❌	Fills the prompt box with base64url text, for deep links.
--deep-link-origin	Undocumented: Only the program shows this item. It can change without notice.	❌	Says that a deep link started this session.
--deep-link-repo <slug>	Undocumented: Only the program shows this item. It can change without notice.	❌	Gives the repo slug that the deep link resolved to the current folder.
--deep-link-last-fetch <ms>	Undocumented: Only the program shows this item. It can change without notice.	❌	Gives the time of the last fetch of the repo, in milliseconds.
--deep-link-cwd-b64 <b64>	Undocumented: Only the program shows this item. It can change without notice.	❌	Gives the working folder as base64url text, for deep links.

Cloud and Remote Sessions

Flags for cloud sessions and Remote Control.

Flag	Status	In --help	What it does
--teleport [session]	Documented: An official docs page names this item.	✅	Resumes a teleport session.
--cloud [description|session_id|url]	Documented: An official docs page names this item.	✅	Creates a cloud session, or attaches to one by session ID or claude.ai/code URL.
--environment <environment_id>	Documented: An official docs page names this item.	✅	Creates a cloud session on a self-hosted environment.
--remote-control [name]	Documented: An official docs page names this item.	✅	Starts an interactive session with Remote Control turned on.
--rc [name]	Documented: An official docs page names this item.	❌	Is an alias for --remote-control.
--remote-control-session-name-prefix <prefix>	Documented: An official docs page names this item.	✅	Sets the prefix of the names that Remote Control makes. The default is the host name.
--remote [description|session_id|url]	Documented: An official docs page names this item. Deprecated: The program or the official docs call this deprecated. Use --cloud	❌	Is a deprecated alias for --cloud.
--pool <pool_id>	Undocumented: Only the program shows this item. It can change without notice. Deprecated: The program or the official docs call this deprecated. Use --environment	❌	Is a deprecated alias for --environment.
--correlation-id <id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets an ID that goes back to the environment orchestrator. It needs --environment.
--ref <ref>	Documented: An official docs page names this item.	❌	Sets the branch, tag, or SHA to check out in the remote session. It needs --cloud or --environment.
--on-branch <branch>	Undocumented: Only the program shows this item. It can change without notice.	❌	Works directly on a branch in the remote session, with checkout and push.
--forward-home-settings <true|false>	Undocumented: Only the program shows this item. It can change without notice.	❌	Sets whether this machine sends its settings to the cloud session.
--attach-serve <session_id>	Undocumented: Only the program shows this item. It can change without notice.	❌	Attaches a helper to a cloud session. The desktop app starts it.

Errors

Each row is a family of messages. The backticked text is the start that every message in the family shares. A row marked Various gathers the messages of one feature that do not share one start.

Start of Message	Status	What It Means	Cases
Various	Undocumented: Only the program shows this item. It can change without notice.	Deep links. Claude Code refused a deep link.	The cwd is not an absolute path. The cwd holds .., control characters, or a network path. The plugin or marketplace value is not valid. The scheme or action is unknown. The launch command cannot be quoted safely.
Various	Undocumented: Only the program shows this item. It can change without notice.	Flag values. Claude Code refused a command-line flag value or combination.	A flag needs another flag. For example, --resume-session-at needs --resume. A flag cannot be combined with a prompt. A flag needs a value in a range. The socket path of --messaging-socket-path is not a private local socket.
Various	Undocumented: Only the program shows this item. It can change without notice.	Claude in Chrome. The Claude in Chrome connection failed.	The bridge is not connected. No extension connected. The browser is not paired. The socket directory or socket has the wrong owner or permissions. Claude Code could not find the browser helper.

Related Pages

• CLI Overview
• Subcommands
• Environment Variables for variables that match many flags.
• Permission Modes for the values of --permission-mode.