| name | claude-cli-flags |
| description | Authoritative, version-pinned reference for every Claude Code CLI flag, classified by whether it works in an INTERACTIVE session (default TUI), a HEADLESS session (-p/--print), or BOTH — plus the canonical launch recipes for each mode. Use when any session needs to launch or script `claude` and must know which switch is valid in which mode, build a headless/streaming invocation, set up remote-control or an always-on session, pass model/effort/permissions/MCP/plugin/settings flags, or answer "does flag X work with -p / in interactive". Trigger: "claude flags", "claude cli switches", "which flags work headless vs interactive", "-p flags", "stream-json flags", "how do I launch claude with X", "/claude-cli-flags". |
claude-cli-flags — interactive vs headless switch reference
NOTE — a common preference: favor interactive, visible sessions over headless -p. Many
setups prefer interactive, visible Claude Code sessions over headless one-shots. A -p call
deliberates with no live window into the reasoning — it can't be watched or caught mid-flight,
which can undercut transparency. If that matters to you, prefer: an interactive session,
--remote-control, or a streamed live session (--input-format/--output-format stream-json), and
reach for -p only with a concrete reason. This is a configurable preference, not a hard rule —
adjust it to your project. The flags below are documented for completeness either way.
Pinned to claude 2.1.183. Source of truth is the binary itself: re-derive anytime with
claude --help. If the installed version differs materially, re-run help and update this file
(the --version check below tells you).
claude --version
The one switch everything pivots on
- no
-p → interactive TUI (default; prompt box, slash commands, pickers).
-p / --print → headless: run the prompt, print, exit. Also: the workspace-trust dialog
is auto-skipped in headless (or any non-TTY/piped stdout) — only run -p in trusted dirs.
See the note above — many setups prefer an interactive/visible session.
HEADLESS-ONLY (args: headless)
The help text explicitly gates these to --print (or to a stream-json format, which implies print).
| Flag | Meaning |
|---|
-p, --print | the headless switch itself |
--output-format <text|json|stream-json> | shape of printed output; stream-json = realtime NDJSON |
--input-format <text|stream-json> | stream-json feeds multiple messages over stdin (always-on programmatic driving) |
--include-partial-messages | stream token deltas (requires --output-format=stream-json) |
--include-hook-events | emit hook lifecycle events into the stream (requires stream-json) |
--replay-user-messages | echo stdin messages back on stdout for ack (stream-json in and out) |
--max-budget-usd <amount> | hard dollar cap for the run |
--no-session-persistence | don't write the session to disk (can't be resumed) |
--fallback-model <m,m,…> | auto-fail-over models when overloaded; retries primary each turn |
--json-schema <schema> | validate/force structured output (print/SDK) |
--prompt-suggestions | in print/SDK, emits a predicted-next-prompt message each turn |
INTERACTIVE-ONLY (args: interactive)
Reference TUI concepts (prompt box, pickers, IDE, panes) — no meaning headless.
| Flag | Why interactive |
|---|
(default, no -p) | the interactive session itself |
--remote-control [name] | "Start an interactive session with Remote Control" (drive from claude.ai/phone) |
--remote-control-session-name-prefix <p> | names auto-generated remote-control sessions |
--ide | auto-connect to an IDE on startup |
--tmux | spawn a tmux session for the worktree (requires --worktree; iTerm2 native panes if available) |
-w, --worktree [name] | new git worktree for the live session |
-n, --name <name> | display name in the prompt box / /resume picker / terminal title |
--from-pr [value] | resume a PR-linked session, or open an interactive picker |
-r, --resume (no value) | interactive picker (WITH a value it resumes by id — works headless too, see Both) |
WORKS IN BOTH (args: both)
Mode-agnostic session configuration — valid with or without -p.
Model / effort
--model <alias|full> · --effort <low\|medium\|high\|xhigh\|max>
Permissions / tools
--permission-mode <acceptEdits\|auto\|bypassPermissions\|default\|dontAsk\|plan> ·
--dangerously-skip-permissions · --allow-dangerously-skip-permissions ·
--allowedTools <…> · --disallowedTools <…> · --tools <…> (""=none, default=all)
Context / prompt
--add-dir <dirs…> · --system-prompt <p> · --append-system-prompt <p> ·
--exclude-dynamic-system-prompt-sections (better prompt-cache reuse; default system prompt only) ·
--file <file_id:relpath…>
Agents / skills
--agent <name> · --agents <json> · --disable-slash-commands · --brief (enables SendUserMessage)
MCP --mcp-config <files|json…> · --strict-mcp-config
Plugins --plugin-dir <path> · --plugin-url <url> (both repeatable)
Settings / auth --settings <file|json> · --setting-sources <user,project,local> · --betas <…>
Session lifecycle -c, --continue · -r, --resume <value> (by id) · --session-id <uuid> · --fork-session
Modes / troubleshooting --bare (minimal; sets CLAUDE_CODE_SIMPLE=1) ·
--safe-mode (all customizations off; sets CLAUDE_CODE_SAFE_MODE=1) ·
-d, --debug [filter] · --debug-file <path> · --verbose · --ax-screen-reader ·
--chrome / --no-chrome · --mcp-debug (deprecated → use --debug)
Canonical recipes (args: recipes)
claude --remote-control my-session
claude --dangerously-skip-permissions --remote-control my-session
claude -p "summarize the diff" --output-format json
claude -p --input-format stream-json --output-format stream-json --include-partial-messages
claude -p "do X" --max-budget-usd 0.50 --fallback-model sonnet,haiku
claude -p -r <session-id> "continue with Y"
Interactive vs headless for always-on work: --remote-control = human + claude.ai both drive one TUI.
The -p --input-format stream-json trio = a program drives it, with structured read-back.
Related
For the in-session / slash commands (not launch flags), see the claude-slash-commands skill.
Not flags — subcommands (args: subcommands)
claude <command>: agents · auth · mcp · plugin|plugins · project · doctor · install ·
update|upgrade · setup-token · ultrareview · auto-mode.
Honesty
- Classification follows the v2.1.183
--help annotations verbatim; "BOTH" = no mode gate stated.
- A flag valid in a mode can still be a no-op if its dependency is absent (e.g.
--tmux needs --worktree;
--include-partial-messages needs --output-format=stream-json).
- Re-confirm against
claude --help if the version moved past 2.1.183.
