CLI flags

All options you can pass when launching Claude Code from the terminal. Run claude —help to see the full list.

Pass CLI flags when you launch Claude Code:

claude [flags] [prompt]

Run claude --help to see all available flags in your installed version.

Flags that configure session behavior (like --model and --permission-mode) can also be changed mid-session with the corresponding slash commands: /model and /permissions.

---

Core flags

-p, --print

Run Claude non-interactively. Claude processes the prompt (from the argument or stdin), prints the response, and exits. No REPL is started.

claude -p "explain the main function in src/index.ts"
echo "what does this do?" | claude -p

The workspace trust dialog is skipped in --print mode. Only use this flag in directories you trust.

Works with: --output-format, --model, --system-prompt, --permission-mode, --max-turns, --allowed-tools.

--output-format <format>

Set the output format. Only works with --print.

Value	Description
text	Plain text output (default)
json	Single JSON object with the complete result
stream-json	Newline-delimited JSON stream with real-time events

claude -p "list the exported functions" --output-format json
claude -p "refactor this file" --output-format stream-json

Use stream-json when you want to process Claude’s output incrementally as it arrives (useful for long-running tasks or piping into other tools).

--input-format <format>

Set the input format for stdin. Only works with --print.

Value	Description
text	Plain text input (default)
stream-json	Newline-delimited JSON stream input

stream-json input requires --output-format stream-json.

cat messages.jsonl | claude -p --input-format stream-json --output-format stream-json

--verbose

Enable verbose output. Overrides the verbose setting in your config file.

claude --verbose
claude -p "debug this" --verbose

-v, --version

Print the version number and exit.

claude --version
claude -v

-h, --help

Display help for the command and exit.

claude --help
claude mcp --help

---

Session continuation flags

-c, --continue

Resume the most recent conversation in the current directory without prompting for a session to resume.

claude --continue
claude -c "now add tests for that"

-r, --resume [session-id]

Resume a conversation by session ID. Without a value, opens an interactive picker where you can search through past sessions. Accepts an optional search term to filter the list.

# Open interactive picker
claude --resume

# Resume by session ID
claude --resume 550e8400-e29b-41d4-a716-446655440000

# Open picker filtered by search term
claude --resume "auth refactor"

--fork-session

When used with --continue or --resume, creates a new session branched from the resumed conversation rather than continuing it in place.

claude --resume <session-id> --fork-session

-n, --name <name>

Set a display name for the session. The name appears in /resume and in the terminal title.

claude --name "auth-refactor"

--session-id <uuid>

Use a specific UUID as the session ID instead of a generated one. Must be a valid UUID. Cannot be used with --continue or --resume unless --fork-session is also specified.

claude --session-id 550e8400-e29b-41d4-a716-446655440000

--no-session-persistence

Disable session persistence. The session will not be saved to disk and cannot be resumed. Only works with --print.

claude -p "one-off task" --no-session-persistence

---

Model and capability flags

--model <model>

Set the model for the session. Accepts an alias (e.g. sonnet, opus, haiku) or a full model ID (e.g. claude-sonnet-4-6).

claude --model sonnet
claude --model opus
claude --model claude-sonnet-4-6

You can also change the model mid-session with /model.

--effort <level>

Set the effort level for the session. Controls how much computation Claude applies to each response.

Value	Description
low	Faster, lighter responses
medium	Balanced (default)
high	More thorough reasoning
max	Maximum effort

claude --effort high "review this architecture"

--fallback-model <model>

Enable automatic fallback to a different model when the primary model is overloaded. Only works with --print.

claude -p "analyze this" --model opus --fallback-model sonnet

---

Permission and safety flags

--permission-mode <mode>

Set the permission mode for the session.

Mode	Behavior
default	Claude prompts before running commands and making edits
acceptEdits	File edits are applied automatically; shell commands still require approval
plan	Claude proposes a plan and waits for your approval before acting
bypassPermissions	All actions run without prompts — intended for sandboxed automated environments only

claude --permission-mode acceptEdits
claude --permission-mode plan "refactor the payment module"
claude --permission-mode bypassPermissions   # only in isolated sandboxes

bypassPermissions disables all confirmation prompts. Only use it inside Docker containers, CI sandboxes, or other isolated environments with no internet access.

--dangerously-skip-permissions

Bypass all permission checks. Claude takes all actions (file edits, shell commands) without asking. Equivalent to --permission-mode bypassPermissions.

claude --dangerously-skip-permissions -p "run the full test suite and fix failures"

Only use this in sandboxed environments with no internet access. Claude Code enforces this: the flag is rejected when running with root/sudo privileges, or outside a Docker or bubblewrap container.

--allow-dangerously-skip-permissions

Make bypassing all permission checks available as an option during the session, without enabling it by default. Useful for automated pipelines that may need to escalate mid-session.

claude --allow-dangerously-skip-permissions -p "..."

--allowed-tools <tools...>

Aliases: --allowedTools

Comma- or space-separated list of tools Claude is allowed to use. Tools not in this list are blocked.

claude --allowed-tools "Bash(git:*) Edit Read"
claude --allowed-tools Bash,Edit,Read

Tool patterns support glob-style matching: Bash(git:*) permits any git command; Edit(src/**) permits edits under src/.

--disallowed-tools <tools...>

Aliases: --disallowedTools

Comma- or space-separated list of tools Claude is not allowed to use.

claude --disallowed-tools "Bash(rm:*)"

--tools <tools...>

Specify the exact set of built-in tools available for the session. Use "" to disable all tools, default to enable all tools, or name specific tools.

# Disable all tools
claude --tools ""

# Enable only Bash and Read
claude --tools "Bash Read"

# Enable the default set
claude --tools default

---

Context and prompt flags

--add-dir <directories...>

Add one or more directories to the tool access context. Claude will be able to read and edit files in these directories in addition to the current working directory.

claude --add-dir /shared/libs --add-dir /shared/config

Useful for monorepos or projects where related code lives outside the current directory.

--system-prompt <prompt>

Override the default system prompt with a custom prompt. Cannot be used with --system-prompt-file.

claude --system-prompt "You are a security auditor. Focus only on vulnerabilities."

--append-system-prompt <text>

Append text to the default system prompt. Unlike --system-prompt, this preserves Claude’s built-in instructions and adds to them.

claude --append-system-prompt "Always suggest test cases for every function you write."

--mcp-config <configs...>

Load MCP servers from one or more JSON config files or inline JSON strings. Multiple values are space-separated.

# Load from a file
claude --mcp-config ./mcp-servers.json

# Load from multiple files
claude --mcp-config ./local-tools.json ./db-tools.json

# Pass inline JSON
claude --mcp-config '{"mcpServers":{"filesystem":{"command":"npx","args":["@modelcontextprotocol/server-filesystem","/tmp"]}}}'

See the MCP servers guide for the config file format.

--strict-mcp-config

Only use MCP servers from --mcp-config, ignoring all other MCP configurations (user config, project config, etc.).

claude --mcp-config ./ci-tools.json --strict-mcp-config

--settings <file-or-json>

Load additional settings from a JSON file path or an inline JSON string.

# From a file
claude --settings ./team-settings.json

# Inline JSON
claude --settings '{"model":"claude-sonnet-4-6","verbose":true}'

--setting-sources <sources>

Comma-separated list of settings sources to load. Controls which settings files are read at startup.

Value	Description
user	Load ~/.claude/settings.json
project	Load .claude/settings.json in the current directory
local	Load .claude/settings.local.json in the current directory

# Load only user-level settings (ignore project settings)
claude --setting-sources user

# Load user and project settings
claude --setting-sources user,project

--agents <json>

Define custom agents inline as a JSON object. Each key is the agent name; the value is an object with description and prompt.

claude --agents '{"reviewer":{"description":"Reviews code for security issues","prompt":"You are a security-focused code reviewer."}}'

---

Output control flags

--include-hook-events

Include all hook lifecycle events in the output stream. Only works with --output-format stream-json.

claude -p "run task" --output-format stream-json --include-hook-events

--max-turns <n>

Limit the number of agentic turns in non-interactive mode. Claude stops after this many turns even if the task is incomplete. Only works with --print.

claude -p "refactor this module" --max-turns 10

--max-budget-usd <amount>

Set a maximum dollar amount to spend on API calls. Claude stops when the budget is reached. Only works with --print.

claude -p "large analysis task" --max-budget-usd 2.50

--json-schema <schema>

Provide a JSON Schema for structured output validation. Claude’s response will be validated against this schema.

claude -p "extract the function names" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

---

Worktree flags

-w, --worktree [name]

Create a new git worktree for this session. Optionally specify a name for the worktree branch. Accepts a PR number or GitHub PR URL to create a worktree from that PR.

claude --worktree
claude --worktree feature-auth
claude --worktree "#142"

--tmux

Create a tmux session alongside the worktree. Requires --worktree. Uses iTerm2 native panes when available; pass --tmux=classic to force standard tmux behavior.

claude --worktree feature-auth --tmux

---

Debug flags

-d, --debug [filter]

Enable debug mode. Optionally pass a filter to restrict which debug categories are shown.

# Show all debug output
claude --debug

# Show only api and hooks categories
claude --debug "api,hooks"

# Exclude specific categories
claude --debug "!file,!1p"

--debug-file <path>

Write debug logs to a specific file path instead of displaying them inline. Implicitly enables debug mode.

claude --debug-file /tmp/claude-debug.log

--bare

Minimal mode. Skips hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. Sets CLAUDE_CODE_SIMPLE=1.

Authentication is limited to ANTHROPIC_API_KEY or apiKeyHelper via --settings (OAuth and keychain are not used).

Use --bare in scripted pipelines where startup latency matters and the features it disables are not needed. You can still provide context explicitly:

claude --bare \
  --system-prompt "$(cat context.md)" \
  --add-dir /project/libs \
  --mcp-config ./tools.json \
  -p "perform the analysis"

---

Flag combinations

Common flag patterns for scripting and automation:

# Non-interactive with JSON output
claude -p "list all exported types" --output-format json

# Bypass permissions in CI (sandboxed environment only)
claude -p "run full test suite and fix failures" --dangerously-skip-permissions

# Resume last session and continue non-interactively
claude --continue -p "now write the tests for that"

# Use a custom MCP config with strict isolation
claude --mcp-config ./ci-mcp.json --strict-mcp-config -p "analyze the schema"

# Append to system prompt without replacing it
claude --append-system-prompt "Always output TypeScript, not JavaScript."