Claude Code CLI Reference

Source: Anthropic official docs — CLI reference Type: Product Reference Product: Claude Code

The complete surface for the claude binary — every subcommand and every flag. This page is the canonical “how do I invoke X from the shell?” lookup. The official claude --help is intentionally short and does not list every flag, so a flag’s absence from --help does not mean it is unavailable.

Quick command map

claude is one binary with several subcommands. Group them by purpose:

Purpose	Commands
Start / continue session	claude, claude "query", claude -c, claude -r
Programmatic / piped	claude -p, cat file | claude -p "query"
Install / update	claude install [version], claude update
Auth	claude auth login, claude auth logout, claude auth status, claude setup-token
Inspect config	claude agents, claude auto-mode defaults
MCP / plugins	claude mcp, claude plugin (alias claude plugins), claude plugin tag, claude plugin prune
Code review	claude ultrareview [target] (W16+, non-interactive Ultrareview)
Project management	claude project purge [path] (deletes all state: transcripts, tasks, file history, config entry; --dry-run, -y, -i, --all)
Remote control	claude remote-control

Mistyped subcommands surface a “Did you mean…?” suggestion and exit without starting a session.

Sessions

Form	What happens
claude	Interactive session in the current directory.
claude "query"	Interactive session, with the first user message pre-filled.
claude -c / --continue	Load the most recent conversation in this directory (includes sessions added via /add-dir).
claude -r <id-or-name>	Resume a specific session by ID, by name, or via picker. --fork-session mints a new ID.
claude -p "query" / --print	Single-shot SDK query, no interactive UI. Programmatic / scripted entry point.
cat file | claude -p "query"	Piped content goes into the same SDK call. Standard non-interactive workflow.
claude --session-id <uuid>	Pin a specific UUID for the conversation (must be valid UUID).
claude -n "name" / --name	Set a session display name (shown in /resume and the terminal title). /rename swaps it mid-session.
claude --from-pr <pr>	Resume sessions linked to a PR (number, GitHub/GHE URL, GitLab MR URL, Bitbucket PR URL). Auto-linked when Claude creates the PR.

Web sessions, remote control, and teleport

The CLI is one of three Claude Code surfaces — local terminal, claude.ai web sessions, and the Claude app. Three flags bridge them:

• --remote "task description" — create a new web session on claude.ai for the task. Runs in Anthropic’s cloud.
• --teleport — pick a running web session and resume it in the local terminal.
• --remote-control / --rc (interactive) or claude remote-control (server-only) — start a local session you can also drive from claude.ai or the Claude app. --remote-control-session-name-prefix (or CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX) sets the auto-generated name prefix.

Auth and install

Command	Purpose
claude auth login	Sign in. --email pre-fills email, --sso forces SSO, --console signs into Anthropic Console for API-key billing instead of a Claude subscription.
claude auth logout	Sign out.
claude auth status	JSON status by default; --text for human-readable. Exit code 0 = logged in, 1 = not.
claude setup-token	Generate a long-lived OAuth token for CI / scripts. Prints to terminal without saving. Requires a Claude subscription.
claude install [version]	Install or reinstall the native binary. Accepts 2.1.118, stable, or latest.
claude update	Update to the latest version.

CLI flags by intent

There are roughly fifty flags; grouping them by what they configure makes the reference scannable.

Permissions and tool surface

Flag	Effect
--permission-mode <mode>	Start in default, acceptEdits, plan, auto, dontAsk, or bypassPermissions. Overrides settings.
--dangerously-skip-permissions	Equivalent to --permission-mode bypassPermissions.
--allow-dangerously-skip-permissions	Add bypassPermissions to the Shift+Tab cycle without starting in it (so you can switch in mid-session).
--allowedTools	Tools that execute without prompting. Pattern syntax (e.g., "Bash(git log *)" "Read").
--disallowedTools	Tools removed from the model’s context entirely.
--tools	Restrict the built-in toolset. "" disables all, "default" enables all, or list ("Bash,Edit,Read").
--disable-slash-commands	Disable all skills and slash commands for this session.
--permission-prompt-tool <mcp-tool>	Route permission prompts through an MCP tool (non-interactive flow only).
--add-dir <path...>	Grant additional working directories for read/edit. .claude/ config is not discovered from these paths.

Model, effort, and budget

Flag	Effect
--model <alias-or-id>	Set model. Aliases sonnet/opus resolve to the latest, or pass full IDs like claude-sonnet-4-6.
--effort <level>	Session-scoped effort: low, medium, high, xhigh, max (availability depends on model). Doesn’t persist to settings. See Opus 4.7 best practices for what xhigh means.
--fallback-model	Auto-fall back to a model when the default is overloaded (print mode only).
--max-turns <N>	Cap agentic turns (print mode only). Exits with error at the limit.
--max-budget-usd <N>	Hard dollar cap on API spend (print mode only).
--betas <header>	Beta headers in API requests (API-key users only).

System prompt

Four flags, two pairs. All work in interactive and non-interactive modes.

Flag	Behavior
--system-prompt <text>	Replace the entire default prompt.
--system-prompt-file <path>	Replace with file contents.
--append-system-prompt <text>	Append to the default prompt.
--append-system-prompt-file <path>	Append from a file.

--system-prompt and --system-prompt-file are mutually exclusive. Append flags can combine with either replace flag. Default to appending — it preserves Claude Code’s built-in capabilities and only adds your requirements. Replace only when you need full control.

Print / non-interactive (-p)

-p / --print flips Claude Code into SDK mode — no interactive UI, prompt → response → exit. The print-only flags below depend on it:

Flag	Effect
--output-format <text|json|stream-json>	Output shape. JSON is one blob; stream-json emits incrementally.
--input-format <text|stream-json>	Input shape (paired with --output-format for full streaming).
--include-hook-events	Include all hook lifecycle events in the output stream. Requires --output-format stream-json.
--include-partial-messages	Include partial streaming events. Requires --print and --output-format stream-json.
--replay-user-messages	Re-emit user messages from stdin on stdout for acknowledgment. Requires --input-format stream-json and --output-format stream-json.
--json-schema <schema>	Validate output against a JSON Schema after the agent completes its workflow.
--no-session-persistence	Don’t save the session to disk; not resumable.
--exclude-dynamic-system-prompt-sections	Move per-machine sections (cwd, env info, memory paths, git status) into the first user message. Improves prompt-cache reuse across users/machines running the same task. Ignored when a custom system prompt is set.

Bare mode and init lifecycle

Flag	Effect
--bare	Skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Bash + file read + file edit only. Sets CLAUDE_CODE_SIMPLE. The fastest scripted entry point.
--init	Run Setup hooks with the init matcher before the session (print mode only via -p).
--init-only	Run Setup and SessionStart hooks, then exit without starting a conversation. Useful for CI one-time setup.
--maintenance	Run Setup hooks with the maintenance matcher before the session (print mode only via -p).

Subagents and agent teams

Flag	Effect
--agent <name>	Pin one subagent for the session (overrides settings).
--agents '<json>'	Define custom subagents inline. Same field names as subagent frontmatter, plus prompt for instructions.
--teammate-mode <mode>	How Agent Teams teammates display: auto (default), in-process, or tmux.

Worktrees and Chrome

Flag	Effect
--worktree <name> / -w	Start in an isolated git worktree at <repo>/.claude/worktrees/<name> (auto-generated name if omitted).
--tmux (or --tmux=classic)	Wrap the worktree in a tmux session. Requires --worktree. Uses iTerm2 native panes when available.
--ide	Auto-connect to IDE on startup if exactly one is available.
--chrome	Enable Chrome browser integration for web automation/testing.
--no-chrome	Disable Chrome integration for this session.

MCP, plugins, channels

Flag	Effect
--mcp-config <files-or-json>	Load MCP servers from JSON files or inline strings (space-separated). See Essential MCP servers.
--strict-mcp-config	Use only what --mcp-config declares — ignore other MCP configurations.
--plugin-dir <path>	Load plugins from a directory for this session only. Repeat the flag for multiple directories.
--channels <plugins>	(Research preview) MCP servers whose channel notifications Claude listens for. Space-separated plugin:<name>@<marketplace>. Requires claude.ai auth.
--dangerously-load-development-channels	Enable channels not on the approved allowlist (local dev). Accepts plugin:<name>@<marketplace> and server:<name>. Confirmation prompt.

Settings, debug, version

Flag	Effect
--settings <path-or-json>	Path to a settings JSON file or inline JSON string for additional settings.
--setting-sources <list>	Comma list of which sources to load: user, project, local.
--debug "<categories>"	Debug mode with category filtering, e.g. "api,hooks" or negated "!statsig,!file".
--debug-file <path>	Write debug logs to a path. Implicitly enables debug mode. Takes precedence over CLAUDE_CODE_DEBUG_LOGS_DIR.
--verbose	Full turn-by-turn logging.
--version / -v	Print version.

Environment variables

The CLI reads several environment variables that aren’t exposed as flags. Most ship via What's New digests; gathered here for lookup:

Variable	Effect
CLAUDE_CODE_SIMPLE	Set automatically by --bare. Skips auto-discovery of hooks, skills, plugins, MCP, auto memory, CLAUDE.md.
CLAUDE_CODE_DEBUG_LOGS_DIR	Default location for debug logs (overridden by --debug-file).
CLAUDE_CODE_DISABLE_CRON	Disables /loop and CronCreate/List/Delete. Already-scheduled tasks stop firing.
CLAUDE_CODE_NO_FLICKER	(W14, v2.1.89) Opt into the alt-screen renderer with virtualized scrollback. Required for W15’s Ctrl+O focus view.
CLAUDE_CODE_USE_POWERSHELL_TOOL	(W13, v2.1.84) Enables the native PowerShell tool on Windows alongside Bash.
CLAUDE_CODE_PERFORCE_MODE	(W15) Edit/Write fail on read-only files with a p4 edit hint instead of silently overwriting.
CLAUDE_CODE_CERT_STORE	(W15) Defaults to os (trusts OS CA store, enterprise TLS proxies work without setup). Set to bundled to opt out.
CLAUDE_CODE_USE_MANTLE	(W15) Set to 1 to route Amazon Bedrock through Mantle.
ENABLE_PROMPT_CACHING_1H	(W16, v2.1.108) Opts API key, Bedrock, Vertex, and Foundry users into 1-hour prompt cache TTL (default is 5 min). High-value for workloads with long prefixes that pause mid-session.
CLAUDE_CODE_FORK_SUBAGENT	(W17) Set to 1 on external builds to enable forked subagents that inherit the full conversation context instead of starting fresh.
ANTHROPIC_BEDROCK_SERVICE_TIER	(v2.1.122) Select a Bedrock service tier.
CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX	Same effect as --remote-control-session-name-prefix.

New slash commands and aliases (W16–W17)

Added since the CLI reference was last updated:

Command / alias	Added	Behavior
/usage	W16 (v2.1.111)	Shows what drives your limits: parallel sessions, subagents, cache misses, long context — each with % of last 24 hrs and an optimization tip. Press d or w for day/week views. Merges old /cost and /stats.
/tui	W16 (v2.1.110)	Toggles between classic and flicker-free rendering mid-conversation. Can also set the tui setting in config.
/focus	W16 (v2.1.110)	Collapses view to last prompt, one-line tool summary with diffstats, and final response. Replaces Ctrl+O.
/recap	W17 (v2.1.108)	On-demand session recap: one-line summary of what happened since you last focused this session. Auto-shown on return; toggle from /config.
/fewer-permission-prompts	W16	Scans transcripts for common read-only Bash and MCP calls and proposes an allowlist entry for .claude/settings.json.
/undo	W16 (v2.1.108)	Alias for /rewind.
/proactive	W16 (v2.1.105)	Alias for /loop. See Scheduled Tasks.
vim v / V	W17 (v2.1.118)	Vim visual mode in the prompt input: v for character selection, V for visual-line, with operators and visual feedback.

Settings additions (W16): sandbox.network.deniedDomains — carves specific domains out of a broader allowedDomains wildcard in the sandbox network config. /config now persists to ~/.claude/settings.json (W17, v2.1.119) — theme, editor mode, verbose, and similar settings survive restarts and follow the project/local/policy precedence chain.

Removed / deprecated

• --enable-auto-mode — removed in v2.1.111. Auto mode is now in the Shift+Tab permission-mode cycle by default; use --permission-mode auto to start there.

Recent Signals

[Reddit signal — r/ClaudeCode 2026-05-09]: r/ClaudeCode post 1t8712b (“20 Claude Code commands worth using”, score 318) inventories operator-level slash commands grouped into stop/undo/branch (Esc, double-Esc//rewind, /btw, /branch), context management (/compact, /clear, /export, /resume, claude -c, claude -r, /remote-control aka /rc), working-smarter (/model opusplan, /simplify, /insights HTML report at ~/.claude/usage-data/report.html, /loop with .claude/loop.md overrides, /skills [name]), and keyboard shortcuts (Ctrl+V paste screenshots, Ctrl+J newline-without-send, Ctrl+R prompt history search, Ctrl+U clear input). Notable hazard surfaced in comments: /model opusplan has an unresolved bug where every subagent runs Opus (very expensive) — flagged for Quick command map consumers to verify before adopting opusplan as default. Verify each entry exists in this reference and append any that are missing during the next refresh pass.

Key Takeaways

• One binary, named subcommands (auth, mcp, plugin, remote-control, agents, auto-mode, setup-token, install, update); everything else is flags on claude.
• claude --help is incomplete by design — refer to this page (or the official source) for the full surface.
• -p / --print is the SDK gateway. Most automation flags (--output-format, --max-turns, --max-budget-usd, --no-session-persistence, --include-hook-events) only apply with -p.
• --bare is the fastest scripted entry — skips auto-discovery of hooks, skills, plugins, MCP, auto memory, CLAUDE.md. Pair with -p for cheap scripted calls.
• --exclude-dynamic-system-prompt-sections is the multi-tenant prompt-cache lever: hoists per-machine state into the user message so the cached prefix is shared across users running the same scripted task.
• --fork-session exists alongside --resume / --continue — the standard way to branch off an existing conversation without overwriting it.
• Three modes for “how does Claude Code talk to claude.ai?”: --remote (push to web), --teleport (pull web back to terminal), --remote-control / claude remote-control (drive local from web/app).
• Mistype protection: claude udpate returns a “Did you mean claude update?” suggestion and exits.

Try It

1. Cheapest non-interactive call. claude --bare -p "summarize this in one line" < notes.txt — no auto memory, no plugins, no MCP, no CLAUDE.md scan. Useful in cron jobs and CI scripts where you just want the model.
2. Force a specific model + effort. claude --model claude-sonnet-4-6 --effort high "..." to pin both for one session without changing settings.
3. Plan-mode start. claude --permission-mode plan so the first turns plan-only; switch to write mode via Shift+Tab once aligned.
4. Worktree-isolated session. claude -w feature-auth --tmux — clean branch + tmux split. Keeps speculative work out of the main checkout.
5. Resume by name. claude -r "auth-refactor" (note: works because you set -n "auth-refactor" when you started). --fork-session if you want a copy that diverges.
6. Web ↔ terminal handoff. claude --remote "Triage open Sentry issues" to spin a web session, then claude --teleport later to pull it down to your terminal.
7. Multi-user prompt-cache reuse. claude -p --exclude-dynamic-system-prompt-sections "..." in scripted multi-user workloads — different users, same cache prefix.
8. CI-safe auth. claude setup-token once locally → store the OAuth token in CI secrets → CI runs claude -p "..." non-interactively against it.

Related

• Claude Code Hooks — --init, --init-only, --maintenance are the CLI entry points to the hook lifecycle.
• Claude Code Scheduled Tasks — /loop is the in-session counterpart; the CLI gives you the flags to start that session.
• Claude Code Channels — --channels and --dangerously-load-development-channels configure which MCP push channels a session listens to.
• Claude Code Agent Teams — --teammate-mode selects how teammates display.
• Claude Code Subagents — --agent pins one; --agents declares them inline.
• Claude Managed Agents — --remote / --teleport connect terminal sessions to the cloud surface.
• Claude Code Routines — durable cloud scheduling counterpart to local CLI invocations.
• Essential MCP Servers — claude mcp, --mcp-config, --strict-mcp-config configure the MCP surface.
• Plugins and Marketplaces — claude plugin (alias plugins), --plugin-dir.
• Opus 4.7 Best Practices — what --effort xhigh means and when to use it.
• Extended Thinking (API Reference) — model-config sibling for the API surface.
• Claude Cowork — --remote creates a new web session on the same surface.
• Ultrareview — slash-command counterpart that runs in a Claude-managed sandbox.

Open Questions

• The page lists claude subcommands but does not include slash commands — those live under a separate “Interactive mode” / commands reference. Worth a future ingest.
• Environment variables referenced (CLAUDE_CODE_SIMPLE, CLAUDE_CODE_DEBUG_LOGS_DIR, CLAUDE_CODE_DISABLE_CRON, CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX) point to a separate /en/env-vars page. Ingest candidate for the env-var matrix.
• The “See also” section names Chrome extension, Interactive mode, Quickstart, Common workflows, Settings, and Agent SDK pages — none currently in the wiki at full depth. Candidate ingests if the surface keeps growing.