--add-dir | Add additional working directories for Claude to read and edit files. Grants file access; Claude Code doesn’t discover most .claude/ configuration from these directories. Validates that each path exists as a directory. You can’t add most network paths, such as \\server\share. To persist these directories across sessions, set permissions.additionalDirectories in settings | claude --add-dir ../apps ../lib |
--advisor <model> | Enable the server-side advisor tool for this session with a model alias, fable, opus, or sonnet, or a full model ID. Takes precedence over the advisorModel setting for the session. fable requires Fable access | claude --advisor opus |
--agent | Specify an agent for the current session (overrides the agent setting) | claude --agent my-custom-agent |
--agents | Define custom subagents dynamically via JSON. Accepts the fields listed for CLI-defined subagents. With --print, the value can instead be the path to a JSON file holding the object; the file form requires Claude Code v2.1.281 or later. Claude Code validates the value at startup and exits on an invalid one; see Invalid --agents configuration for the message and for the flags and environment variable that skip the validation. Validation requires Claude Code v2.1.242 or later | 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, --allowed-tools | Tools that execute without prompting for permission, apart from reads from network paths. See permission rule syntax for pattern matching. To restrict which tools are available, use --tools instead. If you name one of the task-tracking tools here, Claude Code also opts the session in | "Bash(git log *)" "Bash(git diff *)" "Read" |
--append-subagent-system-prompt | Append custom text to the end of every subagent’s system prompt, nested subagents included, apart from a forked subagent, which reuses the conversation’s own prompt. Only applies in non-interactive mode with -p. Requires Claude Code v2.1.205 or later | claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query" |
--append-subagent-system-prompt-file | Load text from a file and append it to subagent system prompts. An alternative to --append-subagent-system-prompt for text too long to pass on the command line. The two flags can’t be combined. Only applies in non-interactive mode with -p. Requires Claude Code v2.1.261 or later | claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query" |
--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 |
--autocompact <auto|tokens> | Set the auto-compact window for this session without changing your saved settings. Accepts the same values as /autocompact; that section covers the value forms and what overrides the flag. Requires Claude Code v2.1.221 or later | claude --autocompact 500k |
--ax-screen-reader | Render screen-reader friendly output: flat text without decorative borders or animations. Forces the classic renderer, so the tui setting has no effect; attached background sessions still render fullscreen. Takes precedence over CLAUDE_AX_SCREEN_READER and the axScreenReader setting. Requires Claude Code v2.1.181 or later | claude --ax-screen-reader |
--bare | Minimal mode: skip auto-discovery of hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster. Skills in a directory you pass with --add-dir still load. 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 |
--bg, --background | Start the session as a background agent and return immediately. Prints the session ID and management commands. Combine with --exec to run a shell command as a background job instead of a Claude session, or with --agent to run a specific subagent. Checks workspace trust for the directory before it starts. Can’t be combined with -p/--print; see the error reference | claude --bg "investigate the flaky test" |
--channels | (Research preview) MCP servers whose channel notifications Claude should listen for in this session. Space-separated list of plugin:<name>@<marketplace> entries. Requires Anthropic authentication through claude.ai or a Console API key | claude --channels plugin:my-notifier@my-marketplace |
--chrome | Enable Chrome browser integration for web automation and testing | claude --chrome |
--cloud | With a task description, create a new cloud session. With a session ID (session_... or cse_...) or a claude.ai/code URL, queue a message into that existing session instead, with -p. See send a follow-up message. | claude --cloud "Fix the login bug" |
--continue, -c | Load the most recent conversation in the current directory, including a background session that has finished; opening finished background sessions requires Claude Code v2.1.257 or later. Skips sessions created with claude -p or the Agent SDK, and sessions whose first prompt was /loop. claude -p --continue includes -p, SDK, and /loop sessions. 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, so it takes effect in interactive sessions. With -p, Claude Code ignores the flag | 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. For sessions started with --bg, the mode persists when the supervisor restarts the session | claude --dangerously-skip-permissions |
--debug | Enable debug mode with optional category filtering, such as --debug='mcp,startup' or --debug='!1p'. The filter binds only in the = form; a space-separated filter enables debug mode without filtering | claude --debug='mcp,startup' |
--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 |
--desktop | Open the Claude Desktop app on the current directory and exit without starting a session in the terminal. Add --continue, or --resume with a session ID, to open that session in Desktop instead. --resume here takes only a session ID, not a name or transcript path. Takes no prompt and no other flags except --verbose and the --debug flags, since the app starts the session itself. Available on macOS and x64 Windows when you’re signed in with a Claude subscription. Requires Claude Code v2.1.285 or later | claude --desktop |
--disable-slash-commands | Disable all skills and commands for this session | claude --disable-slash-commands |
--disallowedTools, --disallowed-tools | Deny rules. A bare tool name removes the matching tools from Claude’s context: "Edit" removes Edit, "*" removes every tool, and "mcp__*" removes every MCP tool. A scoped rule such as Bash(rm *) leaves the tool available and denies only calls that match as written. A rule naming EndConversation can’t remove it while any other tool remains | "Bash(git log *)" "Bash(git diff *)" "Edit" |
--effort | Set the effort level for the current session. Options: low, medium, high, xhigh, max, or ultracode. Available levels depend on the model. ultracode requests xhigh effort with ultracode turned on, and requires Claude Code v2.1.203 or later. Overrides the modelSettings and effortLevel settings for this session and does not persist | 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 |
--environment <environment-id> | Create a new cloud session that runs on the self-hosted environment with the given ID. Environment IDs start with ccpool_. See --environment dispatch behavior for dispatch behavior and the flag combinations it rejects. Requires Claude Code v2.1.224 or later | claude -p "Fix the login bug" --environment ccpool_abc123 |
--exclude-dynamic-system-prompt-sections | Move per-user context, such as the auto memory location, out of the system prompt and 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" |
--exec | Run a shell command as a PTY-backed background job instead of starting a Claude session. Use with --bg to launch from the shell | claude --bg --exec 'pytest -x' |
--fallback-model | Enable automatic fallback to the specified model(s) when the primary model is overloaded or not available, for example a retired model. Accepts a comma-separated list tried in order. See Fallback model chains. To persist a chain across sessions, use the fallbackModel setting, which this flag overrides | claude --fallback-model sonnet,haiku |
--fork-session | When resuming, create a new session ID instead of reusing the original (use with --resume or --continue) | claude --resume abc123 --fork-session |
--forward-subagent-text | Emit subagent text and thinking blocks in the output stream as assistant and user messages with parent_tool_use_id set, so you can reconstruct each subagent’s transcript. Without this flag, Claude Code omits the text and thinking blocks of a subagent that runs in the foreground. Requires --print and --output-format stream-json. For nested subagents, forked skills, and the version each needs, see Follow subagent messages. The CLAUDE_CODE_FORWARD_SUBAGENT_TEXT environment variable enables the same behavior. Requires Claude Code v2.1.211 or later | claude -p --output-format stream-json --verbose --forward-subagent-text "query" |
--from-pr | Open the session picker filtered to 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 hook lifecycle events in the output stream. SessionStart and Setup hook events are always included and don’t need this flag. Some hook events, such as Notification, SessionEnd, PreCompact, and PostCompact, never produce a hook_started event, even with this flag. For those events, Claude Code still emits hook_progress while a command hook that runs for more than a second produces output, and emits hook_response only when a hook that runs in the background finishes. Requires --output-format stream-json | claude -p --output-format stream-json --verbose --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 --verbose --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 the agent completes its workflow (print mode only). See structured outputs. Claude Code exits with an error on an invalid schema and accepts the format keyword as an annotation without client-side validation | 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 | Stop the run once estimated spend on API calls reaches this amount (print mode only). Claude Code checks the cap against its client-side cost estimate, which can differ from your bill. Spend from subagents counts toward the cap. Spend can pass the cap, so leave headroom. When you return to a conversation with --continue or --resume, totals restored from earlier runs don’t count toward it. Once spend reaches the cap, spawning another subagent fails with Budget limit reached, and Claude Code stops background subagents that are still running; the cap-enforcement behaviors require Claude Code v2.1.217 or later | 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. With --input-format stream-json, a message still queued when the limit ends a turn stays queued and starts a new turn with its own limit | claude -p --max-turns 3 "query" |
--mcp-config | Load MCP servers from JSON files or strings (space-separated). When you pass this flag with -p, Claude Code waits for still-pending servers to connect before running the first turn, up to the MCP_TIMEOUT startup timeout, 30 seconds by default; a server with a cached tool list skips the wait and connects on first use. In a self-hosted environment, a shorter wait applies instead. The wait requires Claude Code v2.1.221 or later | claude --mcp-config ./mcp.json |
--model | Sets the model for the current session with a model alias such as sonnet, opus, haiku, or fable, or a model’s full name. Overrides the model setting and ANTHROPIC_MODEL | claude --model claude-sonnet-5 |
--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, bypassPermissions, or manual as an alias for default. The manual alias selects the permission mode the UI labels Manual and requires Claude Code v2.1.200 or later; claude --help lists it in place of default, and both values work. Overrides defaultMode from settings files. Without this flag or --dangerously-skip-permissions, a new session starts in the permission mode described in which permission mode a session starts in, which also covers what a -p run starts in | claude --permission-mode plan |
--permission-prompt-tool | Specify an MCP tool to handle permission prompts in non-interactive mode. Claude Code waits for that tool’s MCP server to connect before running the first turn, up to the MCP_TIMEOUT startup timeout, 30 seconds by default.
The prompt tool can’t approve an MCP tool marked as requiring user interaction: Claude Code converts an allow result for one to a deny. This restriction requires Claude Code v2.1.199 or later | claude -p --permission-prompt-tool mcp_auth_tool "query" |
--permission-prompts | Set who answers permission prompts in print mode. With the default host, Claude Code sends them to the Agent SDK host or the --permission-prompt-tool tool. Pass none when nobody can answer, and Claude Code denies them instead. See Turn off permission prompts in unattended runs. Requires Claude Code v2.1.259 or later | claude -p --permission-prompts none "query" |
--plugin-dir | Load a plugin from a directory or .zip archive, or several from a folder of plugins, for this session only. Each flag takes one path. Repeat the flag for more paths: --plugin-dir A --plugin-dir B.zip. Passing a folder of plugins requires Claude Code v2.1.265 or later | claude --plugin-dir ./my-plugin |
--plugin-url | Fetch a plugin .zip archive from a URL for this session only. Repeat the flag for multiple plugins, or pass space-separated URLs in a single quoted value | claude --plugin-url https://example.com/plugin.zip |
--print, -p | Print response without interactive mode (see Agent SDK documentation for programmatic usage details). For --resume on a background session that is still running, see Resume a running background session | claude -p "query" |
--prompt-suggestions | Emit a prompt_suggestion message with a predicted next user prompt after each turn that generates one; very short conversations can produce none. Requires --print, --output-format stream-json, and --verbose. See Prompt suggestions | claude -p --prompt-suggestions --output-format stream-json --verbose "query" |
--ref <branch> | With --environment, base the new session’s checkout on a named ref instead of local HEAD | claude -p "Run the smoke test" --environment ccpool_abc123 --ref main |
--remote | Deprecated alias for --cloud, including the existing-session form | 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 --verbose --replay-user-messages |
--restricted | Start in restricted mode. Use it when an evaluation harness drives claude on a shared machine and Claude Code must not run commands or read that machine’s user and project settings. Claude Code removes the built-in tools that run commands or code, and WebFetch, unless you name them individually in --tools, not through the default preset. It also confines the built-in file tools to the working directories, loads only managed settings and --settings, refuses bypassPermissions, and refuses to create cloud sessions. Requires Claude Code v2.1.248 or later | claude --restricted -p "query" |
--resume, -r | Resume a specific session by ID or name, or show an interactive picker to choose a session. In place of an ID, you can pass the absolute path to a session’s .jsonl transcript file. The picker and name search include sessions that added this directory with /add-dir. When you pass a session ID, Claude Code searches the current project directory and its git worktrees, then every other project on this machine. Before v2.1.223, the ID search covered only the current project directory and its git worktrees. Background sessions appear in the picker marked with bg. Resuming one that is still running opens that session in this terminal through claude attach, and a prompt you pass on the command line goes to it as its next turn. Before v2.1.285, Claude Code refused and printed the claude attach command to run instead | claude --resume auth-refactor |
--safe-mode | Start with all customizations disabled to troubleshoot a broken configuration: CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, custom themes, custom keybindings, status line and file-suggestion commands, LSP servers, and auto memory do not load. Authentication, model selection, built-in tools, and permissions work normally, which differs from --bare. Managed settings policy still applies, including policy-configured hooks, status line, and file-suggestion commands; managed plugins, managed skills, managed CLAUDE.md, and policy-configured MCP servers do not. Useful for checking whether a customization is what triggers automatic model fallback. Sets CLAUDE_CODE_SAFE_MODE | claude --safe-mode |
--session-id | Use a specific session ID for the conversation (must be a valid UUID) | claude --session-id "550e8400-e29b-41d4-a716-446655440000" |
