What does claude -p do?

It runs Claude Code once without the interactive screen. It takes your prompt, works through the task, prints the result and exits. It is how you use Claude Code in scripts, Git hooks and CI. Pipe text into it to give it input, as in cat error.log | claude -p "explain this".

What is the difference between claude -c and claude -r?

claude -c reopens the most recent conversation in the current folder with no questions. claude -r reopens a particular one, by name or id, or shows a list to choose from when you give neither.

Should I use --system-prompt or --append-system-prompt?

Almost always --append-system-prompt. It adds your rules and keeps Claude Code's own instructions, including how to use its tools safely. --system-prompt replaces all of them, which only makes sense for an agent that is not meant to be a coding assistant.

Why does claude --help not show every flag?

The help text leaves some flags out. A flag missing from claude --help can still work; the reference on this page lists them all.

Claude Code CLI flags and commands: the full reference

The claude command starts a session; flags change how it starts. The ones you will use most are -c to continue the last conversation, -r to pick an older one, -p to answer once and exit (for scripts), --model to choose the model, --permission-mode to start in plan or another mode, and -w to work in a separate Git worktree.

Daily use

Take this page into your AI

ChatGPT Claude

Everything starts with claude. Typed alone in a folder it opens an interactive session there. Flags after it change how that session starts, and a few words after it, such as claude update, run a separate job and exit.

Flags apply to one session. To make a choice stick, such as a default model or a permission rule, put it in a settings file instead. A flag overrides the settings for that session.

The flags you will use every day

claude -c                         # carry on with the last conversation here
claude -r                         # pick an older conversation from a list
claude -r billing-bug             # reopen the one you named billing-bug
claude -n billing-bug             # start one and give it that name
claude --model opus               # start with a particular model
claude --permission-mode plan     # start in plan mode: read and propose, no edits
claude -w fix-header              # work in a separate Git worktree

-w is worth knowing early. It creates a Git worktree under .claude/worktrees/, a second checkout of the same repository on its own branch, and starts the session inside it. 2 sessions in 2 worktrees can edit at the same time without touching each other's files.

One-off and scripted runs

-p (print) is the flag that turns Claude Code into a command-line tool. It runs the task, prints the answer and exits:

claude -p "summarize what changed in the last 5 commits"
git diff main | claude -p "write a pull request description for this diff"
claude -p "list every TODO in src/ as JSON" --output-format json

Several flags only work with -p, because they only make sense when no one is watching: --max-turns and --max-budget-usd stop a run that goes on too long, --output-format json returns the result with its cost and session id, and --json-schema makes the answer match a shape your script can read. Scripts and CI covers these runs in full.

Permissions from the command line

You can set what a session may do as you start it:

claude --allowedTools "Bash(npm test *)" "Bash(git diff *)" "Read"
claude --disallowedTools "Bash(git push *)" "WebFetch"

--allowedTools lets matching calls run without asking. --disallowedTools blocks them. --tools goes further and decides which built-in tools exist at all.

--dangerously-skip-permissions turns every permission prompt off. The name is the warning: use it only on a machine or container you can throw away, never on your own laptop with your keys and your production access. Permissions explains the safer options.

Adding to Claude Code's instructions

--append-system-prompt "..." adds text to the end of the instructions Claude Code gives the model, and --append-system-prompt-file does the same from a file. Use them for rules that belong to one run, such as a reply language or an output format.

--system-prompt replaces those instructions entirely, including the guidance on using tools safely. Keep it for agents that are not coding assistants, such as a script that sorts support tickets. For rules your whole project follows, CLAUDE.md is the better place.

Commands that do not start a session

claude update installs the latest version, claude doctor checks your install, and claude auth status tells a script whether it is signed in. claude mcp add connects MCP servers and claude plugin install adds plugins. claude setup-token makes a long-lived token for CI.

Mistype one and Claude Code suggests the closest match instead of starting a session: claude udpate asks whether you meant claude update.

Every flag and command

Search by name or by job, such as "resume", "budget" or "worktree". claude --help leaves some flags out, so this list is longer than what it prints.

Find a flag or command

Show

105 flags and commands

claudeStart
Starts an interactive session in the current folder. Put a task in quotes after it to start with that message.
claude "explain how the build works"
--continue, -cStart
Reopens the most recent conversation in this folder.
claude -c
--resume, -rStart
Reopens a conversation by its name or id, or shows a list to pick from. Add a message to send it straight away.
claude -r auth-refactor "finish the tests"
--fork-sessionStart
With --resume or --continue, copies the conversation into a new session instead of adding to the old one.
claude -r auth-refactor --fork-session
--name, -nStart
Names the session, so claude --resume can find it by that name.
claude -n "billing-bug"
--session-idStart
Uses a session id you choose, which must be a UUID.
claude --session-id "550e8400-e29b-41d4-a716-446655440000"
--from-prStart
Lists only the sessions linked to a pull request, by number or link.
claude --from-pr 123
--worktree, -wStart
Starts in a separate Git worktree under .claude/worktrees/, so this session's edits do not collide with another's. Pass a pull request number to branch from it.
claude -w feature-auth
--tmuxStart
With --worktree, opens the session in its own tmux session or iTerm2 pane.
claude -w feature-auth --tmux
--add-dirStart
Lets Claude read and edit files in more folders than the one you started in.
claude --add-dir ../shared ../docs
--bg, --backgroundStart
Starts the session in the background and returns at once, printing its id. Watch it with claude agents.
claude --bg "investigate the flaky test"
--execStart
With --bg, runs a shell command as a background job instead of a Claude session.
claude --bg --exec 'pytest -x'
--version, -vStart
Prints the version.
claude -v
--modelModel
Sets the model for this session, by alias (sonnet, opus, haiku, fable) or full name.
claude --model opus
--effortModel
Sets how much the model reasons for this session, from low to max. Not saved.
claude --effort high
--fallback-modelModel
Names models to switch to, in order, if the main one is overloaded or gone.
claude --fallback-model sonnet,haiku
--advisorModel
Gives the session a second model to ask for advice at hard moments.
claude --advisor opus
--autocompactModel
Sets how full the context window gets before it compacts, for this session only.
claude --autocompact 500k
--betasModel
Adds beta headers to API requests. API key users only.
claude --betas interleaved-thinking
--permission-modePermissions
Starts in a permission mode - default (Manual), acceptEdits, plan, auto, dontAsk or bypassPermissions.
claude --permission-mode plan
--allowedToolsPermissions
Tools, or patterns of them, that run without asking. Quote each rule.
claude --allowedTools "Bash(npm test *)" "Read"
--disallowedToolsPermissions
Deny rules. A bare tool name removes the tool; a pattern such as "Bash(rm *)" blocks only matching calls.
claude --disallowedTools "Bash(git push *)"
--toolsPermissions
Limits which built-in tools exist at all. "" for none, "default" for the usual set, or a list.
claude --tools "Read,Edit,Bash"
--dangerously-skip-permissionsPermissions
Skips permission prompts, the same as --permission-mode bypassPermissions. Only for isolated machines or containers.
claude --dangerously-skip-permissions
--allow-dangerously-skip-permissionsPermissions
Adds bypassPermissions to the Shift+Tab cycle without starting in it.
claude --permission-mode plan --allow-dangerously-skip-permissions
--permission-prompt-toolPermissions
In a script, sends permission questions to an MCP tool of yours to answer.
claude -p --permission-prompt-tool mcp_auth_tool "query"
--permission-promptsPermissions
In a script, none denies every permission question when nobody is there to answer.
claude -p --permission-prompts none "query"
--restrictedPermissions
Restricted mode for test harnesses on shared machines - no tools that run commands or code, file tools kept to the working folders, and no user or project settings.
claude --restricted -p "query"
--print, -pScripts
Answers once and exits, with no interactive session. The basis of every script and CI job. Pipe text in to give it input.
cat error.log | claude -p "explain this error"
--output-formatScripts
With -p, prints text, json (one object with the result, cost and session id) or stream-json (one event per line).
claude -p "list the API routes" --output-format json
--input-formatScripts
With -p, reads input as text or as a stream of JSON messages.
claude -p --input-format stream-json --output-format stream-json
--json-schemaScripts
With -p, returns JSON that matches the schema you give, checked when the task ends.
claude -p --json-schema '{"type":"object"}' "summarize the diff"
--max-turnsScripts
With -p, stops after this many agent turns and exits with an error.
claude -p --max-turns 5 "fix the lint errors"
--max-budget-usdScripts
With -p, stops once the estimated spend reaches this many dollars. The estimate can differ from your bill, so leave room.
claude -p --max-budget-usd 2 "review this PR"
--no-session-persistenceScripts
With -p, does not save the session, so it cannot be resumed.
claude -p --no-session-persistence "query"
--bareScripts
Skips loading hooks, skills, plugins, MCP servers, memory and CLAUDE.md, so scripted runs start faster and behave the same on every machine.
claude --bare -p "query"
--verboseScripts
Shows the full output of every turn. Needed with -p and stream-json.
claude -p --output-format stream-json --verbose "query"
--include-partial-messagesScripts
With stream-json, also sends the answer as it is written, piece by piece.
claude -p --output-format stream-json --verbose --include-partial-messages "query"
--include-hook-eventsScripts
With stream-json, also reports when hooks start and finish.
claude -p --output-format stream-json --verbose --include-hook-events "query"
--forward-subagent-textScripts
With stream-json, includes what subagents write, so each one's transcript can be rebuilt.
claude -p --output-format stream-json --verbose --forward-subagent-text "query"
--replay-user-messagesScripts
With stream-json in and out, echoes each message it receives back on its output.
claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages
--prompt-suggestionsScripts
With stream-json, adds a guess at your next prompt after each turn.
claude -p --prompt-suggestions --output-format stream-json --verbose "query"
--exclude-dynamic-system-prompt-sectionsScripts
Moves per-user details out of the system prompt so the same job run by many users shares the prompt cache.
claude -p --exclude-dynamic-system-prompt-sections "query"
--initScripts
With -p, runs your Setup hooks with the init matcher before the task.
claude -p --init "query"
--init-onlyScripts
Runs the Setup and SessionStart hooks, then exits.
claude --init-only
--maintenanceScripts
With -p, runs your Setup hooks with the maintenance matcher before the task.
claude -p --maintenance "query"
--append-system-promptPrompt
Adds your text to the end of Claude Code's own instructions, keeping them.
claude --append-system-prompt "Answer in British English"
--append-system-prompt-filePrompt
Adds the contents of a file to the end of Claude Code's own instructions.
claude --append-system-prompt-file ./style.md
--system-promptPrompt
Replaces Claude Code's instructions entirely, including its guidance on tools and safety. For agents that are not coding assistants.
claude -p --system-prompt "You sort support tickets" "query"
--system-prompt-filePrompt
Replaces Claude Code's instructions with the contents of a file.
claude --system-prompt-file ./prompts/triage.txt
--system-prompt-snapshotPrompt
off rebuilds the system prompt on every request instead of keeping the one the conversation started with, useful while you tune it.
claude --system-prompt-snapshot off
--append-subagent-system-promptPrompt
With -p, adds your text to every subagent's instructions.
claude -p --append-subagent-system-prompt "Cite file paths" "query"
--append-subagent-system-prompt-filePrompt
With -p, adds a file's contents to every subagent's instructions.
claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"
--settingsExtend
Loads settings from a file or a JSON string for this session, on top of your settings files.
claude --settings ./ci-settings.json
--setting-sourcesExtend
Chooses which settings files load - user, project, local.
claude --setting-sources user,project
--mcp-configExtend
Loads MCP servers from JSON files or strings.
claude --mcp-config ./mcp.json
--strict-mcp-configExtend
Uses only the MCP servers from --mcp-config and ignores all others.
claude --strict-mcp-config --mcp-config ./mcp.json
--agentExtend
Runs the session as one of your subagents, with its instructions and tools.
claude --agent code-reviewer
--agentsExtend
Defines subagents for this session as JSON.
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You review code for bugs"}}'
--plugin-dirExtend
Loads a plugin from a folder or .zip for this session only. Repeat it for more.
claude --plugin-dir ./my-plugin
--plugin-urlExtend
Downloads a plugin .zip from a link for this session only.
claude --plugin-url https://example.com/plugin.zip
--disable-slash-commandsExtend
Turns off all skills and commands for this session.
claude --disable-slash-commands
--safe-modeExtend
Starts with every customization off - CLAUDE.md, skills, plugins, hooks, MCP servers, memory - to find out whether one of them is causing a problem.
claude --safe-mode
--chromeExtend
Turns on Claude in Chrome for browser tasks.
claude --chrome
--no-chromeExtend
Turns off Claude in Chrome for this session.
claude --no-chrome
--ideExtend
Connects to your code editor at start, if exactly one is found.
claude --ide
--channelsExtend
Listens for messages pushed by channel plugins, such as a chat app or your own server. Research preview.
claude --channels plugin:my-notifier@my-marketplace
--dangerously-load-development-channelsExtend
Allows channels that are not on the approved list, for testing your own.
claude --dangerously-load-development-channels server:webhook
--teammate-modeExtend
Sets how agent team members are shown - in-process, auto, tmux or iterm2.
claude --teammate-mode tmux
--cloudCloud
Starts a new session in the cloud with the task you give, or sends a message to an existing cloud session.
claude --cloud "fix the login bug"
--teleportCloud
Brings a cloud session into your terminal.
claude --teleport
--remote-control, --rcCloud
Starts a session you can also drive from claude.ai or the Claude app.
claude --rc "my project"
--remote-control-session-name-prefixCloud
Sets the start of automatic Remote Control session names, which is otherwise your computer's name.
claude remote-control --remote-control-session-name-prefix dev-box
--environmentCloud
Starts a cloud session on your organization's own self-hosted environment.
claude -p "run the smoke test" --environment ccpool_abc123
--refCloud
With --environment, starts the cloud session from a named branch instead of your current commit.
claude -p "run the smoke test" --environment ccpool_abc123 --ref main
--desktopCloud
Opens the Claude desktop app on this folder, or on a session with --continue or --resume.
claude --desktop --continue
--debugDebug
Turns on debug logging, optionally for some areas only.
claude --debug='mcp,startup'
--debug-fileDebug
Writes the debug log to a file you name.
claude --debug-file /tmp/claude-debug.log
--ax-screen-readerDebug
Plain output for screen readers, with no borders or animation.
claude --ax-screen-reader
claude updateSubcommands
Installs the newest version now.
claude update
claude installSubcommands
Installs or reinstalls the program, at a version, stable or latest.
claude install stable
claude doctorSubcommands
Checks the install and your settings files without starting a session.
claude doctor
claude auth loginSubcommands
Signs in. --console bills a Console account instead of a Claude plan; --sso forces single sign-on.
claude auth login --console
claude auth logoutSubcommands
Signs out.
claude auth logout
claude auth statusSubcommands
Shows how you are signed in, as JSON, and exits with 0 if you are and 1 if not. --text for plain words.
claude auth status --text
claude setup-tokenSubcommands
Makes a long-lived sign-in token for CI and scripts, printed once and not saved. Needs a Claude plan.
claude setup-token
claude mcpSubcommands
Adds, lists and removes MCP servers.
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp loginSubcommands
Signs in to an MCP server that needs it, without opening /mcp. --no-browser prints the link instead, for SSH.
claude mcp login sentry
claude mcp logoutSubcommands
Removes an MCP server's saved sign-in.
claude mcp logout sentry
claude pluginSubcommands
Installs, lists and manages plugins. Also claude plugins.
claude plugin install code-review@claude-plugins-official
claude agentsSubcommands
Opens agent view, to start and watch sessions running in the background. --json lists them for scripts.
claude agents
claude attachSubcommands
Joins a background session in this terminal.
claude attach 7c5dcf5d
claude logsSubcommands
Prints the latest output of a background session.
claude logs 7c5dcf5d
claude stopSubcommands
Stops a background session. Also claude kill.
claude stop 7c5dcf5d
claude respawnSubcommands
Restarts a background session with its conversation, for example to pick up a new version. --all for every one.
claude respawn --all
claude rmSubcommands
Removes a background session from the list. Its transcript stays on your machine.
claude rm 7c5dcf5d
claude daemonSubcommands
Looks after the process that hosts background sessions - logs, run, status and stop.
claude daemon status
claude remote-controlSubcommands
Runs a server so you can start and drive sessions on this machine from claude.ai or the Claude app.
claude remote-control --name "work laptop"
claude importSubcommands
Brings settings, instructions, MCP servers and skills over from OpenAI Codex, Gemini CLI or Cursor.
claude import codex --dry-run
claude purgeSubcommands
Deletes everything Claude Code stored locally for a project - transcripts, edit history, prompt history. --dry-run previews.
claude purge ~/work/repo --dry-run
claude auto-mode defaultsSubcommands
Prints the rules auto mode's safety check uses, as JSON. claude auto-mode config shows yours with your settings applied.
claude auto-mode defaults
claude auto-mode resetSubcommands
Removes your own auto mode rules from your user settings, back to the defaults.
claude auto-mode reset
claude ultrareviewSubcommands
Runs the deep cloud code review from a script and prints the findings. --post adds them to a GitHub pull request.
claude ultrareview 1234 --json
claude gatewaySubcommands
Runs a self-hosted gateway that signs a company's developers in and sends their requests to Bedrock, Google Cloud or Foundry. For administrators.
claude gateway --config gateway.yaml
claude self-hosted-runnerSubcommands
Registers this machine to run your organization's cloud sessions on its own infrastructure.
claude self-hosted-runner setup

Questions

What does claude -p do?: It runs Claude Code once without the interactive screen. It takes your prompt, works through the task, prints the result and exits. It is how you use Claude Code in scripts, Git hooks and CI. Pipe text into it to give it input, as in cat error.log | claude -p "explain this".
What is the difference between claude -c and claude -r?: claude -c reopens the most recent conversation in the current folder with no questions. claude -r reopens a particular one, by name or id, or shows a list to choose from when you give neither.
Should I use --system-prompt or --append-system-prompt?: Almost always --append-system-prompt. It adds your rules and keeps Claude Code's own instructions, including how to use its tools safely. --system-prompt replaces all of them, which only makes sense for an agent that is not meant to be a coding assistant.
Why does claude --help not show every flag?: The help text leaves some flags out. A flag missing from claude --help can still work; the reference on this page lists them all.

Sources