Running claude starts an interactive session in the current directory. claude -p "..." runs one prompt and exits, and with --output-format json returns a result object carrying result, session_id, total_cost_usd, usage, num_turns, and duration_ms. -c continues the last session, -r resumes one by id or name, -w starts in an isolated git worktree, and --bg starts a background agent you reattach to later. This page is the working subset, current as of August 2026.
claude -p "..."runs one prompt and exits. This is the scripting entry point.--output-format jsonreturns cost, token usage, turn count, and a session id.-ccontinues the last session;-r <id-or-name>resumes a specific one.-w <name>starts the session in its own git worktree, isolated from the main checkout.--bgruns the session in the background;claude agents,attach, andlogsmanage it.--bareskips discovery of hooks, skills, plugins, MCP, and CLAUDE.md. Use it in CI.
The forms you will actually use
Nine of these cover almost everything.
| Command | Does |
|---|---|
claude | Interactive session in the current directory |
claude "fix the failing test" | Interactive, with an opening prompt |
claude -p "summarise this repo" | One-shot: print the answer and exit |
cat err.log | claude -p "explain" | Read from stdin, capped at 10MB |
claude -c | Continue the most recent conversation in this directory |
claude -r "auth-refactor" "finish it" | Resume a session by id or name |
claude -w feature-auth | Start in an isolated git worktree |
claude update | Update to the newest version now |
claude doctor | Read-only install and settings diagnostics |
claude mcp | Manage MCP servers |
claude setup-token | Generate a long-lived OAuth token for CI and scripts |
The background-session verbs
This is the half of the CLI that most people never find. --bg starts a session as a background agent and returns immediately; a supervisor process hosts it, and a separate set of commands manages the fleet.
| Command | Does |
|---|---|
claude --bg "investigate the flaky test" | Start a background agent and return straight away |
claude --bg --exec 'pytest -x' | Run a shell command as a PTY-backed background job, no agent |
claude agents | Open the agent view to monitor and dispatch background sessions |
claude agents --json | The same, machine-readable |
claude attach 7c5dcf5d | Attach to a background session in this terminal |
claude logs 7c5dcf5d | Print recent output from a background session |
claude respawn 7c5dcf5d | Restart a background session with its conversation intact |
claude stop 7c5dcf5d | Stop it (alias claude kill) |
claude rm 7c5dcf5d | Remove it from the list |
claude daemon status | Print the background-session supervisor state |
The flags, grouped by what they control
Sessions and continuity
| Flag | Effect |
|---|---|
-c, --continue | Load the most recent conversation in this directory |
-r, --resume | Resume by session id or name, or show an interactive picker |
--fork-session | On resume, create a new session id instead of reusing the original |
--session-id | Use a specific session id (must be a valid UUID) |
-n, --name | Give the session a display name, shown in /resume and the terminal title |
--no-session-persistence | Do not write the session to disk |
-w, --worktree | Create an isolated worktree and start there |
--tmux | Create a tmux session for the worktree (requires --worktree) |
Model, effort, and thinking
| Flag | Effect |
|---|---|
--model | Alias (sonnet, opus, haiku, fable) or a full model id |
--effort | low, medium, high, xhigh, max, or ultracode |
--fallback-model | Fall back automatically when the primary model is overloaded |
--advisor | Enable the server-side advisor tool with a model alias or id |
--autocompact | Set the auto-compact window for this session |
Permissions, tools, and directories
| Flag | Effect |
|---|---|
--permission-mode | Start in a named mode; see the table below |
--allowedTools | Tools that execute without prompting, using permission-rule syntax |
--disallowedTools | Deny rules; a bare name removes the tool entirely |
--tools | Restrict which built-in tools Claude can use at all |
--add-dir | Grant read and edit access to additional directories |
--dangerously-skip-permissions | Equivalent to --permission-mode bypassPermissions |
--permission-prompt-tool | An MCP tool that answers permission prompts non-interactively |
Output and scripting
| Flag | Effect |
|---|---|
-p, --print | Non-interactive: answer and exit |
--output-format | text, json, or stream-json |
--input-format | text or stream-json |
--json-schema | Validate the final answer against a JSON Schema, returned in structured_output |
--include-partial-messages | Emit token-level deltas (needs -p and stream-json) |
--forward-subagent-text | Emit subagent text and thinking blocks into the stream |
--max-turns | Cap the number of agentic turns (print mode only) |
--max-budget-usd | Stop after this much API spend (print mode only) |
--verbose | Full turn-by-turn output |
Configuration and startup
| Flag | Effect |
|---|---|
--bare | Skip discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md |
--settings | A settings file path, or an inline JSON string |
--setting-sources | Which of user, project, local to load |
--mcp-config | Load MCP servers from JSON files or strings |
--strict-mcp-config | Use only the servers from --mcp-config |
--agents | Define custom subagents inline as JSON |
--append-system-prompt | Append text to the default system prompt |
--system-prompt | Replace the system prompt entirely |
--safe-mode | Start with all customizations disabled, to isolate a broken config |
--debug | Debug output, with optional category filtering |
Print mode is the interesting one
With -p, Claude Code stops being an application and becomes a command. That makes it composable with everything else you already have.
# explain a failure
npm test 2>&1 | claude -p "why did this fail? one paragraph."
# review a diff before pushing
git diff main... | claude -p "review this diff, list only real bugs"
# a commit message from staged changes
git diff --cached | claude -p "write a conventional commit message, no body"
# machine-readable, for a script
claude -p "list the exported functions in src/api.ts" --output-format json{
"type": "result",
"result": "The exported functions are ...",
"session_id": "3f2a8c14-...",
"is_error": false,
"num_turns": 3,
"duration_ms": 8210,
"duration_api_ms": 7440,
"total_cost_usd": 0.0184,
"usage": { "input_tokens": 41230, "output_tokens": 612 },
"modelUsage": {
"claude-sonnet-5": { "input_tokens": 41230, "output_tokens": 612 }
}
}# force the answer into a shape
claude -p "extract the exported function names from auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
| jq '.structured_output'
# stream tokens as they are generated
claude -p "explain recursion" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'The scripting details that bite once and then never again.
| Behaviour | Detail |
|---|---|
| Exit codes | 0 on success, non-zero on failure, 143 after SIGTERM |
| Failures inside the run | Printed as the result on stdout, not on stderr |
| Invalid flags | Reported to stderr before the run starts |
| stdin cap | 10MB. Beyond that, write a file and reference the path |
| Background shells | Terminated about five seconds after the final result |
| Background subagents | Waited for, capped at ten minutes by default |
Skills in -p | Include /skill-name in the prompt string; it is expanded before the run |
Permission modes
The values --permission-mode accepts, and what each is for.
| Mode | Behaviour | Use for |
|---|---|---|
default | Prompts before each consequential action (shown as Manual in the mode indicator) | Normal interactive work |
plan | Reads and analyses only; proposes a plan and edits nothing | Anything large or unfamiliar |
acceptEdits | Writes files without prompting, and auto-approves mkdir, touch, mv, cp | Trusted, well-scoped tasks |
auto | A classifier decides which actions still need you | Reducing prompt fatigue without going open loop |
dontAsk | Denies anything outside your allow rules and the read-only command set | Locked-down CI runs |
bypassPermissions | No prompts at all | Containers and disposable VMs only |
Plan mode is the one that repays learning. Agreeing an approach before any file changes prevents the expensive failure, which is a long confident run in the wrong direction that you then have to unwind. <kbd>Shift</kbd>+<kbd>Tab</kbd> cycles modes mid-session, so you can drop into plan the moment a task turns out bigger than you thought.
Worktree sessions from the CLI
Running two agents in one checkout means they overwrite each other. -w makes that structurally impossible without you managing git by hand.
claude -w feature-auth
claude -w bugfix-login # in another terminal
# from a pull request; quote it so the shell does not eat the #
claude --worktree "#1234"
# with its own tmux session
claude -w feature-auth --tmuxBy default the worktree is created under .claude/worktrees/<name>/ at your repository root, on a branch named worktree-<name>, branched from the repository default branch. Omit the name and Claude Code generates one. Add .claude/worktrees/ to your .gitignore.
Questions people ask
Use claude -p "your prompt", which answers and exits. Add --output-format json for a machine-readable result carrying the answer, the session id, token usage, and total_cost_usd. Add --bare in CI so the run does not pick up local hooks, plugins, or CLAUDE.md.
claude -c continues the most recent conversation in the current directory. claude -r resumes a specific one by session id or by the name you gave it with -n, or shows an interactive picker if you pass nothing.
Yes, in print mode. Piping works as you would expect, which is what makes patterns like npm test 2>&1 | claude -p "why did this fail?" useful. Piped stdin is capped at 10MB; beyond that, write a file and reference its path.
Pass --model with an alias such as sonnet or opus, or a full model id. It applies to that invocation only. --effort sets the reasoning level separately, from low through max.
It prints read-only installation and settings diagnostics without starting a session: install health, PATH, settings-file validation errors, the result of the last update attempt, and suggested fixes. Run it before concluding anything is broken.
Give each one its own git worktree with claude -w name. Claude Code creates it under .claude/worktrees/, and then actively blocks that session from editing the main checkout, running commands there, or redirecting git into it.
--print runs one prompt in the foreground and exits with the answer. --bg starts a full session as a background agent and returns immediately, and you manage it afterwards with claude agents, claude attach, claude logs, and claude stop.
Inside a container or disposable VM, yes, because the sandbox is the boundary. On your own machine it lets the agent run any command without asking. If you want fewer prompts without that trade, use the sandboxed Bash tool or --permission-mode auto instead.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.