CLI reference
Every claude subcommand and launch flag, grouped by job, plus how the system prompt flags combine and behave across resumed conversations.
This page covers what you type at the shell, before a session starts: the claude subcommands and the flags you can launch with. Commands you type inside a session are on Commands, and keyboard behaviour is on Interactive mode.
Two things worth knowing up front. claude --help does not list every flag, so do not assume a flag is missing because help omits it. And if you mistype a subcommand, Claude Code suggests the nearest one and exits without starting a session (claude udpate replies Did you mean claude update?).
Starting and resuming sessions
| Invocation | Effect | Example |
|---|---|---|
claude | Interactive session | claude |
claude "prompt" | Interactive session that starts with a prompt | claude "walk me through the auth middleware" |
claude -p "prompt" | Non-interactive: run, print, exit | claude -p "list the env vars this app reads" |
<cmd> | claude -p "prompt" | Feed piped input to a one-shot run | git diff main | claude -p "write a changelog entry" |
claude -c | Continue the latest conversation in this directory | claude -c |
claude -c -p "prompt" | Continue non-interactively | claude -c -p "now add tests for that" |
claude -r "<session>" "prompt" | Resume by id or name with a new prompt | claude -r "invoice-export" "finish the CSV columns" |
See Headless for everything about -p, and Sessions for resuming.
Subcommands
Account and installation
| Command | What it does |
|---|---|
claude update | Update to the latest version |
claude install [version] | Install or reinstall the native binary: a version such as 2.1.118, or stable or latest. See Setup |
claude auth login | Sign in. --email pre-fills your address, --sso forces SSO, --console signs in with the Anthropic Console for API billing instead of a subscription |
claude auth logout | Sign out |
claude auth status | JSON auth status (--text for human-readable). Exit 0 if signed in, 1 if not. authMethod is one of none, claude.ai, oauth_token, api_key, api_key_helper, third_party; configDirectory names the config directory in use (v2.1.268) |
claude setup-token | Print a long-lived OAuth token for CI and scripts without saving it. Needs a subscription. See Authentication |
claude doctor | Read-only diagnostics without starting a session: install health, settings validation errors, Remote Control eligibility. The in-session /doctor can also fix things |
claude purge [path] | Delete all local state for a project: transcripts, task lists, debug logs, edit history, prompt history lines and its ~/.claude.json entry. No path opens a picker. --dry-run, -y/--yes, -i/--interactive, --all. See The .claude directory |
claude import [source] | Start a session that runs /import for config from other coding agents; accepts --dry-run and --yes. Not on third-party providers or without feature-flag fetching. v2.1.213 |
Background sessions and agent view
| Command | What it does |
|---|---|
claude agents | Open agent view. --cwd <path> filters by start directory; --json prints active sessions (--json --all includes finished ones). --permission-mode, --model, --effort, --agent set defaults for dispatched sessions; --settings, --add-dir, --plugin-dir, --mcp-config work as for claude. Needs an interactive terminal |
claude attach <id|name> | Attach this terminal to a background session (partial names from v2.1.290) |
claude logs <id|name> | Print recent output from a background session |
claude stop <id> | Stop a background session. Also claude kill |
claude respawn <id> | Restart a session (running or stopped) with its conversation; --all restarts every running one, useful after an upgrade |
claude rm <id> | Remove a session from the list; the transcript stays available to --resume. If removal is refused over its worktree, the message tells you the exact --discard-unpushed <commit>@<worktree-id> (v2.1.260) or --force-remove-worktree <worktree-id> (v2.1.268) to pass |
claude daemon status | Supervisor state, version, socket directory and worker count; exits 1 if not running |
claude daemon logs | Follow ~/.claude/daemon.log until Ctrl+C |
claude daemon run | Run the supervisor in the foreground |
claude daemon stop --any | Stop the supervisor and its sessions; --keep-workers leaves sessions running for the next supervisor to reconnect. Use to recover from an unresponsive supervisor |
If you alias claude to include --dangerously-skip-permissions or --allow-dangerously-skip-permissions, daemon subcommands still work, because only those two leading flags are allowed in front of daemon. Any other flag before daemon stops it running.
Integrations and services
| Command | What it does |
|---|---|
claude mcp | Manage MCP servers; see MCP |
claude mcp login <name> | Run an HTTP, SSE or connector server's OAuth flow without /mcp. --no-browser prints the URL for SSH use; paste the redirect back |
claude mcp logout <name> | Clear a server's stored OAuth credentials |
claude plugin | Manage plugins (alias claude plugins); see the plugin CLI reference |
claude remote-control | Run a Remote Control server with no local interactive session |
claude auto-mode defaults | Print built-in auto mode classifier rules as JSON; --label <prefix> filters case-insensitively. claude auto-mode config shows your effective config. v2.1.208 |
claude auto-mode reset | Remove autoMode from user settings after confirmation (-y skips). Managed and --settings rules still apply. v2.1.212. See Auto mode configuration |
claude ultrareview [target] | Non-interactive ultrareview: findings to stdout, exit 0 or 1. --json, --timeout <minutes> (default 45), and --post to post findings to a github.com PR as one comment (--no-post is the default) |
claude gateway --config gateway.yaml | Run the self-hosted Claude apps gateway for SSO and policy in front of Bedrock, Agent Platform or Foundry |
claude self-hosted-runner | Register this machine with a self-hosted environment and host cloud sessions. setup for a guided walkthrough, doctor to diagnose, orchestrator for on-demand runners. v2.1.224 |
Flags
Choosing the model and how hard it thinks
| Flag | Purpose | Example |
|---|---|---|
--model | Model for this session, by alias (sonnet, opus, haiku, fable) or full name. Beats the model setting and ANTHROPIC_MODEL | claude --model opus |
--fallback-model | Comma-separated models to try in order when the primary is overloaded or unavailable. Overrides the fallbackModel setting | claude --fallback-model sonnet,haiku |
--effort | low, medium, high, xhigh, max or ultracode (xhigh plus ultracode, v2.1.203) for this session only; levels depend on the model | claude --effort xhigh |
--advisor <model> | Turn on the advisor with fable, opus, sonnet or a model id | claude --advisor opus |
--betas | Extra beta headers (API key users only) | claude --betas interleaved-thinking |
--autocompact <auto|tokens> | Auto-compact window for this session without saving it (v2.1.221) | claude --autocompact 400k |
Model configuration explains aliases, effort and fallback chains.
Permissions and tools
| Flag | Purpose | Example |
|---|---|---|
--permission-mode | Start in default (alias manual, v2.1.200), acceptEdits, plan, auto, dontAsk or bypassPermissions. Overrides defaultMode | claude --permission-mode plan |
--dangerously-skip-permissions | Same as --permission-mode bypassPermissions. Persists for --bg sessions when the supervisor restarts them | claude --dangerously-skip-permissions |
--allow-dangerously-skip-permissions | Put bypassPermissions in the Shift+Tab cycle without starting there | claude --permission-mode plan --allow-dangerously-skip-permissions |
--allowedTools, --allowed-tools | Rules that run without prompting. Naming a task-tracking tool also opts the session into it | --allowedTools "Bash(npm test *)" "Read" |
--disallowedTools, --disallowed-tools | Deny rules. A bare name removes the tool entirely ("Edit", "*", "mcp__*"); a scoped rule like Bash(git push *) only blocks matching calls. EndConversation cannot be removed while other tools remain | --disallowedTools "Bash(git push *)" |
--tools | Restrict built-in tools: "" for none, "default", or names like "Read,Grep,Edit". On macOS, Linux and WSL the default set omits Glob and Grep. Does not affect MCP tools | claude --tools "Read,Edit,Bash" |
--permission-prompt-tool | MCP tool that answers permission prompts in -p. Claude Code waits for its server up to MCP_TIMEOUT (30s default). It cannot approve MCP tools marked as needing user interaction | claude -p --permission-prompt-tool mcp__guard__approve "..." |
--permission-prompts | Who answers prompts in print mode: host (default) or none to deny them. v2.1.259 | claude -p --permission-prompts none "..." |
--restricted | For evaluation harnesses on shared machines: removes command and code-running tools and WebFetch unless named individually in --tools, confines file tools to working directories, loads only managed and --settings config, refuses bypassPermissions and cloud sessions. v2.1.248 | claude --restricted -p "..." |
Rule syntax is on Permissions; modes on Permission modes; tool names on the tools reference.
System prompt
| Flag | Behaviour |
|---|---|
--system-prompt | Replace the default prompt with this text |
--system-prompt-file | Replace it with a file's contents |
--append-system-prompt | Add text after the default prompt |
--append-system-prompt-file | Add a file's contents after the default prompt |
--system-prompt-snapshot | on (default) reuses the prompt recorded on the first request; off rebuilds every request (v2.1.257) |
--append-subagent-system-prompt | Append text to every subagent's prompt, nested ones included, except forked subagents (which reuse the conversation's prompt). -p only. v2.1.205 |
--append-subagent-system-prompt-file | File form of the above; cannot be combined with it. -p only. v2.1.261 |
--exclude-dynamic-system-prompt-sections | Move per-user details (such as the auto memory path) out of the system prompt into the first user message, so the prompt caches across users and machines. Default prompt only; for -p multi-user workloads |
The first five work in both interactive and non-interactive mode. See the system prompt section below.
Context, configuration and directories
| Flag | Purpose | Example |
|---|---|---|
--add-dir | Extra directories Claude can read and edit. Grants file access only; most .claude/ config there is not discovered. Paths must exist; most network paths are refused. Persist with permissions.additionalDirectories | claude --add-dir ../shared-ui ../api |
--settings | Settings file or inline JSON; overrides matching keys for this session. Regular file, max 2 MiB | claude --settings ./ci-settings.json |
--setting-sources | Which of user, project, local to load | claude --setting-sources user |
--agent | Run the session as a named agent (overrides the agent setting) | claude --agent release-manager |
--agents | Define subagents inline as JSON (or, with --print, a path to a JSON file, v2.1.281). Validated at start-up (v2.1.242) | claude --agents '{"copyeditor":{"description":"Checks UK spelling","prompt":"You edit copy into UK English"}}' |
--mcp-config | Load MCP servers from JSON files or strings. With -p, waits for pending servers up to MCP_TIMEOUT unless their tool list is cached | claude --mcp-config ./mcp.ci.json |
--strict-mcp-config | Use only --mcp-config servers. See Managed MCP for interaction with a managed file | claude --strict-mcp-config --mcp-config ./mcp.json |
--plugin-dir | Load a plugin folder or zip (or a folder of plugins, v2.1.265) for this session; repeat per path | claude --plugin-dir ./site-release |
--plugin-url | Fetch plugin zips from URLs for this session | claude --plugin-url https://cdn.example.com/p.zip |
--disable-slash-commands | Turn off all skills and commands | claude --disable-slash-commands |
--bare | Skip auto-discovery of hooks, skills, commands, subagents, plugins, MCP servers, auto memory and CLAUDE.md (skills in --add-dir still load). Sets CLAUDE_CODE_SIMPLE | claude --bare -p "..." |
--safe-mode | Troubleshooting: disable CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, custom themes and keybindings, status line and file-suggestion commands, LSP servers and auto memory, while auth, model, built-in tools and permissions work normally. Managed policy (including its hooks and status line) still applies; managed plugins, skills, CLAUDE.md and MCP servers do not. Sets CLAUDE_CODE_SAFE_MODE | claude --safe-mode |
Sessions, naming and background work
| Flag | Purpose | Example |
|---|---|---|
--continue, -c | Load the latest conversation here, including finished background sessions (v2.1.257). Skips -p, SDK and /loop-started sessions unless used with -p. Includes sessions that /add-dired this folder | claude -c |
--resume, -r | Resume by id, name or absolute .jsonl transcript path, or open the picker. Ids are searched in this project and its worktrees, then everywhere on the machine (v2.1.223). Resuming a running background session attaches to it, and a prompt is sent as its next turn | claude -r invoice-export |
--fork-session | With resume or continue, create a new session id instead of reusing the old one | claude -c --fork-session |
--session-id | Use a specific UUID | claude --session-id 2f1b... |
--name, -n | Display name for the session, used by /resume and the terminal title; clashing names get a variant | claude -n "vat-report" |
--from-pr | Picker filtered to sessions linked to a PR or MR (number, GitHub, GitHub Enterprise, GitLab or Bitbucket URL) | claude --from-pr 482 |
--no-session-persistence | Do not save the session (print mode). CLAUDE_CODE_SKIP_PROMPT_HISTORY does the same in any mode | claude -p --no-session-persistence "..." |
--bg, --background | Start as a background agent and return immediately, printing the id and management commands. Checks workspace trust. Not with -p | claude --bg "find why the nightly import is slow" |
--exec | With --bg, run a shell command as a PTY-backed background job instead of a Claude session | claude --bg --exec 'npm run e2e' |
--worktree, -w | Start in a git worktree at <repo>/.claude/worktrees/<name> (name generated if omitted). #123, a GitHub PR URL or a GitLab MR URL (v2.1.233) branches from that PR. See Worktrees | claude -w invoice-export |
--tmux | With -w, create a tmux session; uses iTerm2 panes where available, or --tmux=classic | claude -w spike --tmux |
--teammate-mode | How agent team teammates display: in-process (default), auto, tmux, iterm2 | claude --teammate-mode tmux |
Cloud, remote and other surfaces
| Flag | Purpose | Example |
|---|---|---|
--cloud | With a task, create a cloud session; with a session id (session_..., cse_...) or claude.ai/code URL plus -p, queue a message into it | claude --cloud "bump Next.js and fix the build" |
--remote | Deprecated alias for --cloud | |
--environment <id> | Run a new cloud session on a self-hosted environment (ccpool_...). v2.1.224 | claude -p "run the smoke tests" --environment ccpool_7d2 |
--ref <branch> | With --environment, base the checkout on a ref rather than local HEAD | --ref release/2.4 |
--teleport | Pull a cloud session into this terminal | claude --teleport |
--remote-control, --rc | Interactive session that is also reachable via Remote Control, optionally named | claude --rc "office laptop" |
--remote-control-session-name-prefix <prefix> | Prefix for generated Remote Control names (default: hostname). Also CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX | claude remote-control --remote-control-session-name-prefix studio |
--desktop | Open the desktop app on this directory and exit; add --continue, or --resume <session-id>, to open that session there. No prompt or other flags apart from --verbose and debug flags. macOS or x64 Windows with a subscription; v2.1.285 | claude --desktop --continue |
--ide | Auto-connect to the IDE if exactly one is available | claude --ide |
--chrome, --no-chrome | Enable or disable Chrome integration | claude --chrome |
--channels | Research preview: listen to these channel plugins (plugin:<name>@<marketplace>, space-separated). Needs claude.ai or Console authentication | claude --channels plugin:deploy-alerts@studio-plugins |
--dangerously-load-development-channels | Load channels not on the allowlist (plugin: or server: entries) after a confirmation; ignored with -p. See the channels reference | claude --dangerously-load-development-channels server:deploys |
Print mode and scripting
| Flag | Purpose | Example |
|---|---|---|
--print, -p | Non-interactive run | claude -p "..." |
--output-format | text, json or stream-json | claude -p "..." --output-format json |
--input-format | text or stream-json | --input-format stream-json |
--json-schema | Return validated JSON matching a schema once the agent finishes. Invalid schemas exit with an error; format is accepted as an annotation only | claude -p --json-schema "$(cat schema.json)" "extract the invoice totals" |
--max-turns | Cap agentic turns; exits with an error at the limit. With stream-json input, a still-queued message starts a new turn with its own limit | claude -p --max-turns 5 "..." |
--max-budget-usd | Stop at an estimated spend, including subagents (resumed totals do not count). Further subagents fail with Budget limit reached and running background ones stop (v2.1.217) | claude -p --max-budget-usd 2.50 "..." |
--include-partial-messages | Partial streaming events; needs -p and stream-json | |
--include-hook-events | Hook lifecycle events in the stream (SessionStart and Setup are always included; some events such as Notification, SessionEnd, PreCompact and PostCompact never produce hook_started). Needs stream-json | |
--forward-subagent-text | Emit foreground subagents' text and thinking as messages with parent_tool_use_id. Needs -p and stream-json; also CLAUDE_CODE_FORWARD_SUBAGENT_TEXT. v2.1.211 | |
--prompt-suggestions | Emit a prompt_suggestion after turns that produce one; needs -p, stream-json and --verbose | |
--replay-user-messages | Echo stdin user messages back on stdout; needs stream-json in and out | |
--init | Run Setup hooks with the init matcher first (print mode) | claude -p --init "..." |
--maintenance | Run Setup hooks with the maintenance matcher first (print mode) | |
--init-only | Run Setup and SessionStart hooks, then exit | claude --init-only |
Output, debugging and accessibility
| Flag | Purpose | Example |
|---|---|---|
--verbose | Full turn-by-turn output; overrides viewMode | claude --verbose |
--debug | Debug mode, optionally filtered by category, but only in the = form: --debug='mcp,hooks' or --debug='!1p' | claude --debug=mcp |
--debug-file <path> | Write debug logs to a file (implies debug); beats CLAUDE_CODE_DEBUG_LOGS_DIR | claude --debug-file ./claude-debug.log |
--ax-screen-reader | Flat, screen-reader friendly output with no borders or animation; forces the classic renderer. Beats CLAUDE_AX_SCREEN_READER and axScreenReader. See Accessibility | claude --ax-screen-reader |
--version, -v | Print the version | claude -v |
--enable-auto-mode was removed in v2.1.111; auto mode is in the Shift+Tab cycle by default, and --permission-mode auto starts there.
How the system prompt flags combine
Use the append flags when Claude should still be a coding assistant that also follows your rules: output format for a script, house conventions, domain context. You keep all the default tool guidance and safety instructions. Use the replace flags only when the job is genuinely different (a non-coding agent in an unattended pipeline, say), accepting that you now own everything the default prompt used to cover.
For a persona you want to switch between, use output styles; for standing project rules, use CLAUDE.md. The SDK guide on system prompts discusses the trade-off at more length.
Combination rules:
- A replace flag and an append flag can be used together: the replacement is used, then your appended text.
- From v2.1.283 a flag and its file form can be combined, e.g.
--append-system-promptwith--append-system-prompt-file. The file's content always comes first, then a blank line, then the inline text, regardless of argument order.
claude -p \
--append-system-prompt-file ./house-style.md \
--append-system-prompt "Use UK English and never use em dashes." \
"Rewrite the pricing page intro"
Caching a custom prompt. If a replacement prompt has a fixed part and a per-run part, put a line containing only __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ between them (v2.1.275). Claude Code splits at the first such line and removes it, so the part above stays cached while the part below varies. See Prompt caching.
Resumed conversations
By default the system prompt is built once, on a conversation's first request, with your flags applied, and recorded in the session. Every later request reuses it until the conversation is compacted, including after --resume or --continue. So if you change the flag text (or drop it) on a later launch, the change only takes effect after compaction or in a new conversation.
Exceptions and switches:
- Outside cloud sessions,
--bareorCLAUDE_CODE_SIMPLE=1turns recording off unless you pass--system-prompt-snapshot on. --system-prompt-snapshot offrebuilds the prompt every request, which is what you want while iterating on appended text across--continueruns.- Before v2.1.268, sessions without feature-flag fetching (including Bedrock, Agent Platform and Foundry) always rebuilt the prompt; before v2.1.265, passing any system prompt flag turned recording off.