reference · last verified 2026-04-10

Claude Code CLI reference

Every documented Claude Code CLI flag and command, organized by what you're trying to do. The canonical source is code.claude.com/docs/en/cli-reference; this page groups the same facts by intent and cross-links the deeper guides we've written.

the 5 flags that matter most in production

claude --bare -p "$PROMPT" \
  --permission-mode dontAsk \
  --settings '{"permissions":{"allow":["Read","Edit","Bash(npm test)"]}}' \
  --max-turns 40 \
  --max-budget-usd 3 \
  --output-format stream-json --verbose --include-partial-messages

--bare for reproducibility, --permission-mode dontAsk for bounded authority, a narrow allow list, --max-turns + --max-budget-usd as safety nets, and --output-format stream-json so you can watch the run.

Commands

The top-level claude subcommands.

claude

Start an interactive session

claude "query"

Start an interactive session with an initial prompt

claude -p "query"

Query via SDK, then exit. The workhorse of automation.

cat file | claude -p "query"

Process piped content

claude -c

Continue most recent conversation in the current directory

claude -r "<session>" "query"

Resume a session by ID or name

claude update

Update to the latest version

claude auth login

claude auth status

Show authentication status as JSON (--text for human-readable)

claude agents

List all configured subagents, grouped by source

claude auto-mode defaults

Print the built-in auto mode classifier rules as JSON

claude mcp

Configure MCP servers

claude plugin

Manage plugins. Alias: claude plugins

claude remote-control

Start a Remote Control server (no local interactive session)

claude setup-token

Generate a long-lived OAuth token for CI and scripts

Headless mode essentials

The headless mode guide →

The flags that turn claude into a one-shot CLI you can script against. Start here if you're building anything unattended.

--print, -p

Print response without interactive mode. The entry point for everything on this page.

claude -p "query"

--bareDeep dive: --bare →

Skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Reproducible, fast, recommended for scripts. Docs say it'll become the default for -p.

claude --bare -p "query"

--output-formatDeep dive: stream-json →

text (default), json, or stream-json. Pick stream-json for live events, json for a single structured envelope.

claude -p "q" --output-format json

--input-format

text (default) or stream-json for print mode.

claude -p --input-format stream-json --output-format json

--include-partial-messages

Emit token-level stream events. Requires --print and --output-format stream-json.

claude -p --output-format stream-json --verbose --include-partial-messages "query"

--include-hook-events

Include hook lifecycle events in the output stream. Requires --output-format stream-json.

--verbose

Show full turn-by-turn output. Commonly paired with --output-format stream-json.

--replay-user-messages

Re-emit user messages from stdin back on stdout. Requires stream-json on both sides.

Permissions and tools

Deep dive: the 6 permission modes →

How Claude decides what it can do without asking. There are six permission modes and three ways to narrow the allowlist.

--permission-mode

One of default, acceptEdits, plan, auto, dontAsk, or bypassPermissions. For unattended CI, dontAsk is the only safe choice.

claude --permission-mode dontAsk

--allowedTools

Tools that execute without prompting. Supports scoped bash like Bash(git diff *).

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

--disallowedTools

Tools removed from the model's context entirely. Stronger than deny — the tool doesn't exist for this run.

claude --disallowedTools "Bash(rm *),Edit"

--tools

Restrict which built-in tools Claude can use. Pass "" to disable all, "default" for all, or a comma list.

claude --tools "Bash,Edit,Read"

--dangerously-skip-permissions

Equivalent to --permission-mode bypassPermissions. Containers and VMs only. The word 'dangerously' is not marketing.

--allow-dangerously-skip-permissions

Add bypassPermissions to the Shift+Tab cycle without starting in it.

--enable-auto-mode

Unlock auto mode. Requires Team/Enterprise/API plan and Sonnet 4.6 or Opus 4.6. Not available on Bedrock/Vertex/Foundry.

--permission-prompt-tool

Specify an MCP tool to handle permission prompts in non-interactive mode.

Limits and budgets

The safety net behind the safety net. Set these on every unattended run.

--max-turns

Cap agentic turns in print mode. Exits with an error on limit reached. No limit by default.

claude -p --max-turns 40 "query"

--max-budget-usd

Hard dollar cap. Run aborts when the cap is hit. Print mode only.

claude -p --max-budget-usd 5.00 "query"

--fallback-model

Automatic fallback to a specified model when the default model is overloaded. Print mode only.

claude -p --fallback-model sonnet "query"

Model and effort

Which model runs the session and how hard it tries.

--model

Alias (sonnet, opus) or full model name.

claude --model claude-sonnet-4-6

--effort

Session effort level: low, medium, high, or max (Opus 4.6 only). Session-scoped.

claude --effort high

System prompt and context

The four prompt-shaping flags and the handful of context flags around them. For scripted runs, appending beats replacing — you keep Claude Code's built-in capabilities.

--append-system-prompt

Append custom text to the default system prompt.

claude --append-system-prompt "Always use TypeScript"

--append-system-prompt-file

Append file contents to the default system prompt.

claude --append-system-prompt-file ./style-rules.txt

--system-prompt

REPLACE the entire default system prompt. Mutually exclusive with --system-prompt-file.

--system-prompt-file

Replace the system prompt with file contents.

--exclude-dynamic-system-prompt-sections

Move per-machine sections (cwd, env, memory paths, git status) from the system prompt into the first user message. Improves prompt-cache reuse across multi-user workloads.

--add-dir

Add additional working directories for file read/edit. Grants file access, not .claude config discovery.

claude --add-dir ../apps ../lib

--settings

Path to a settings JSON file or a JSON string.

--setting-sources

Comma list of setting sources: user, project, local.

MCP servers

Bring Model Context Protocol servers into the session. Pair with --bare for reproducibility.

--mcp-config

Load MCP servers from JSON files or strings (space-separated).

claude --mcp-config ./mcp.json

--strict-mcp-config

Only use servers from --mcp-config, ignoring every other source.

Agents and plugins

Subagents and plugin loading for this session.

--agent

Specify an agent for this session, overriding the agent setting.

--agents

Define custom subagents dynamically via JSON. Uses subagent frontmatter fields plus a prompt field.

--plugin-dir

Load plugins from a directory for this session. Repeat for multiple directories.

--disable-slash-commands

Disable all skills and commands for this session.

Session management

Continue, resume, name, fork, or discard sessions.

--continue, -c

Load the most recent conversation in the current directory.

claude -c -p "follow-up question"

--resume, -r

Resume a specific session by ID or name, or open a picker.

claude --resume auth-refactor

--session-id

Use a specific session ID for the conversation. Must be a valid UUID.

--fork-session

On resume, create a new session ID instead of reusing the original.

--name, -n

Display name for the session, shown in /resume and the terminal title.

claude -n "feature-work"

--no-session-persistence

Don't save the session to disk. Print mode only.

--from-pr

Resume sessions linked to a GitHub PR by number or URL.

claude --from-pr 123

Worktrees and panes

Deep dive: git worktree →

Run isolated Claude Code sessions in their own git worktrees. Every background agent ends up doing this.

--worktree, -w

Start Claude in an isolated git worktree at <repo>/.claude/worktrees/<name>.

claude -w feature-auth

--tmux

Create a tmux session for the worktree. Requires --worktree.

Structured output

Schema-driven results, for when you're piping into automation that doesn't want to guess.

--json-schema

Get validated JSON output matching a JSON Schema after the agent completes. Print mode only.

claude -p --json-schema '{"type":"object",...}' "query"

Debug and diagnostics

When something is wrong and you need to know why.

--debug

Debug mode with category filtering like "api,hooks" or "!statsig,!file".

claude --debug "api,mcp"

--debug-file <path>

Write debug logs to a path. Implies --debug.

--betas

Beta headers to include in API requests (API key users only).

--init

Run initialization hooks and start interactive mode.

--init-only

Run initialization hooks and exit.

--maintenance

Run maintenance hooks and start interactive mode.

--version, -v

Print the version number.

IDE and browser

Connect to external surfaces.

--ide

Auto-connect to IDE if exactly one is available.

--chrome

Enable Chrome browser integration for web automation and testing.

--no-chrome

Disable Chrome integration for this session.

Web and remote sessions

Control Claude Code from claude.ai, or kick off a cloud session.

--remote

Create a new Claude Code web session with the provided task description.

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.

--remote-control-session-name-prefix

Prefix for auto-generated Remote Control session names.

--teleport

Resume a web session in your local terminal.

Channels and agent teams

Research previews.

--channels

MCP servers whose channel notifications to listen for. Space-separated plugin:<name>@<marketplace> entries.

--dangerously-load-development-channels

Enable channels not on the approved allowlist, for local development.

--teammate-mode

How agent-team teammates display: auto, in-process, or tmux.

flags, flags, flags

You now know every flag. Cyrus wires them up for you.

Worktree isolation, bare mode, narrow allowlists, stream-json piped to the Linear issue as it updates — all the reference patterns on this page, already shipped, BYOK across Claude/Codex/Cursor/Gemini. Community self-hosted is free forever.

Try Cyrus free →