CLI flags
Customize Claude Code's behavior with these command-line flags. claude --help does not list every flag, so a flag's absence from --help does not mean it is unavailable.
| Flag | Description | Example |
|---|---|---|
--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. Claude Code validates the JSON at startup and exits on an invalid value; 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 | <code v-pre>claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'</code> |
--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. 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, 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. 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 web session on claude.ai. 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 | 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 |
--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 |