--add-dir | Add additional working directories for Claude to read and edit files. Grants file access; most .claude/ configuration is not discovered from these directories. Validates each path exists as a directory. 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, opus or sonnet, or a full model ID. Takes precedence over the advisorModel setting for the session. Claude Code doesn’t offer Fable 5 as the advisor: claude --advisor fable exits with an error | 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. Uses the same field names as subagent frontmatter, plus a prompt field for the agent’s instructions | claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}' |
--allow-dangerously-skip-permissions | Add bypassPermissions to the Shift+Tab mode cycle without starting in it. Lets you begin in a different mode like plan and switch to bypassPermissions later. See permission modes | claude --permission-mode plan --allow-dangerously-skip-permissions |
--allowedTools, --allowed-tools | Tools that execute without prompting for permission. See permission rule syntax for pattern matching. To restrict which tools are available, use --tools instead | "Bash(git log *)" "Bash(git diff *)" "Read" |
--append-subagent-system-prompt | Append custom text to the end of every subagent’s system prompt, including nested subagents. 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-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 |
--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, plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster. Claude has access to Bash, file read, and file edit tools. Sets CLAUDE_CODE_SIMPLE. See bare mode | claude --bare -p "query" |
--betas | Beta headers to include in API requests (API key users only) | claude --betas interleaved-thinking |
--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. Cannot 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 | Create a new web session on claude.ai with the provided task description | claude --cloud "Fix the login bug" |
--continue, -c | Load the most recent conversation in the current directory. Includes sessions that added this directory with /add-dir | claude --continue |
--dangerously-load-development-channels | Enable channels that are not on the approved allowlist, for local development. Accepts plugin:<name>@<marketplace> and server:<name> entries. Prompts for confirmation | claude --dangerously-load-development-channels server:webhook |
--dangerously-skip-permissions | Skip permission prompts. Equivalent to --permission-mode bypassPermissions. See permission modes for what this does and does not skip. 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 (for example, "api,hooks" or "!statsig,!file") | claude --debug "api,mcp" |
--debug-file <path> | Write debug logs to a specific file path. Implicitly enables debug mode. Takes precedence over CLAUDE_CODE_DEBUG_LOGS_DIR | claude --debug-file /tmp/claude-debug.log |
--disable-slash-commands | Disable all skills and commands for this session | claude --disable-slash-commands |
--disallowedTools, --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 matching calls. 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 starts the session at xhigh effort with ultracode turned on, and requires Claude Code v2.1.203 or later. Overrides the effortLevel setting 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 |
--exclude-dynamic-system-prompt-sections | Move per-machine sections from the system prompt (working directory, environment info, memory paths, git-repo flag) 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 emits only subagent tool_use and tool_result blocks. Requires --print and --output-format stream-json. 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 from every hook event in the output stream. SessionStart and Setup hook events are always included and don’t need this flag. 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. Before v2.1.205, an invalid schema produced unstructured output with no error, and schemas using format were treated as invalid | 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 | Maximum dollar amount to spend on API calls before stopping (print mode only). Spend from subagents counts toward the cap. 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 sent while Claude is working stays queued and runs as its own turn, with its own limit, when the limit ends the current one. Before v2.1.205, Claude Code discarded that message | claude -p --max-turns 3 "query" |
--mcp-config | Load MCP servers from JSON files or strings (space-separated) | claude --mcp-config ./mcp.json |
--model | Sets the model for the current session with an alias for the latest model (sonnet, 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 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 | 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 of 30 seconds. Before v2.1.206, a slow-starting server could make the run exit with an error that the MCP tool was not found.
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" |
--plugin-dir | Load a plugin from a directory or .zip archive for this session only. Each flag takes one path. Repeat the flag for multiple plugins: --plugin-dir A --plugin-dir B.zip | 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) | claude -p "query" |
--prompt-suggestions | Emit a prompt_suggestion message after each turn with a predicted next user prompt. Requires --print, --output-format stream-json, and --verbose. See Prompt suggestions | claude -p --prompt-suggestions --output-format stream-json --verbose "query" |
--remote | Deprecated alias for --cloud | 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 |
--resume, -r | Resume a specific session by ID or name, or show an interactive picker to choose a session. The picker and name search include sessions that added this directory with /add-dir; passing a session ID searches only the current project directory and its git worktrees. As of v2.1.144, background sessions appear in the picker marked with bg | 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" |
--setting-sources | Comma-separated list of setting sources to load (user, project, local) | claude --setting-sources user,project |
--settings | Path to a settings JSON file or an inline JSON string. Values you set here override the same keys in your settings.json files for this session. Keys you omit keep their file-based values. The file must be a regular file no larger than 2 MiB. See settings precedence | claude --settings ./settings.json |
--strict-mcp-config | Only use MCP servers from --mcp-config, ignoring all other MCP configurations | claude --strict-mcp-config --mcp-config ./mcp.json |
--system-prompt | Replace the entire system prompt with custom text | claude --system-prompt "You are a Python expert" |
--system-prompt-file | Load system prompt from a file, replacing the default prompt | claude --system-prompt-file ./custom-prompt.txt |
--teleport | Resume a web session in your local terminal | claude --teleport |
--teammate-mode | Set how agent team teammates display: in-process (default), auto, tmux, or iterm2 (added in v2.1.186). The default changed from auto in v2.1.179. Overrides the teammateMode setting for this session. See Choose a display mode | claude --teammate-mode auto |
--tmux | Create a tmux session for the worktree. Requires --worktree. Uses iTerm2 native panes when available; pass --tmux=classic for traditional tmux | claude -w feature-auth --tmux |
--tools | Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read". The flag doesn’t affect MCP tools; to deny those too, use --disallowedTools "mcp__*", or pass --strict-mcp-config without --mcp-config so no MCP servers load. A list that omits EndConversation doesn’t remove it; "" removes it only when no MCP tools remain | claude --tools "Bash,Edit,Read" |
--verbose | Enable verbose logging, shows full turn-by-turn output. Overrides the viewMode setting for this session | claude --verbose |
--version, -v | Output the version number | claude -v |
--worktree, -w | Start Claude in an isolated git worktree at <repo>/.claude/worktrees/<name>. If no name is given, one is auto-generated. Pass #<number> or a GitHub pull request URL to fetch that PR from origin and branch the worktree from it | claude -w feature-auth |