Skip to main content

Headless and Print Mode

Print mode runs one prompt, prints the answer, and exits. Use it in scripts, pipes, and CI. It is also the base of the Agent SDK. Add -p (or --print) to start it. For example, claude -p "Summarize README.md" --output-format json prints one JSON result. Send the prompt as an argument or on stdin. Print mode still saves the session to ~/.claude/projects/. Add --no-session-persistence to save nothing.

warning

Print mode skips the workspace trust dialog. This also happens when stdout is not a terminal, such as when you pipe or redirect output. Use it only in folders you trust.

Source: Run Claude Code Programmatically, CLI Reference, and claude --help. These flags have their rows, with status and details, on CLI Flags.

  • Output and input: -p, --print, --output-format, --input-format, --include-partial-messages, --include-hook-events, --forward-subagent-text, and --replay-user-messages.
  • Checks and limits: --json-schema and --max-budget-usd.
  • Prompts and permissions: --prompt-suggestions and --permission-prompts.
  • Lean runs: --no-session-persistence, --bare, and --restricted.
  • Tools, models, sessions, and MCP: --allowedTools, --disallowedTools, --tools (see CLI Flags), --fallback-model (see Models), --resume, --continue, --fork-session, --session-id (see Sessions and Storage), and --mcp-config with --strict-mcp-config (see MCP Settings and Policy).

Example​

One JSON answer, with a budget and a schema
claude -p "List the three biggest files in this repo" \
  --output-format json \
  --max-budget-usd 1 \
  --json-schema '{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}}},"required":["files"]}'
Watch the answer grow, line by line
claude -p "Explain this repo" --output-format stream-json --verbose --include-partial-messages \
  | while read -r line; do echo "$line" | jq -r '.type'; done

The second command prints a system line for init, then stream_event lines, then one result line.

How It Works​

The loop is the same as in interactive mode. See Agent Loop. Permission prompts have no screen to appear on, so a host program (or --permission-prompts none) must decide.

Pages in This Section​

PageWhat It Covers
Stream JSON MessagesEvery message type that print mode writes
Control ProtocolEvery control request a host can send on the same stream

Errors​

Each row is a family of messages. The backticked text is the start that every message in the family shares. A row marked Various gathers the messages of one feature that do not share one start.

Start of MessageStatusWhat It MeansCases
Various
Undocumented: Only the program shows this item. It can change without notice.
Agent SDK. The Agent SDK or the control protocol refused an option or a request.A skill name is not valid. The caller used sessionStore with an option that it cannot work with. The caller did not provide a callback such as canUseTool or getOAuthToken. A control request subtype is not supported. A value has the wrong type. Claude Code did not find the native CLI binary.
Various
Undocumented: Only the program shows this item. It can change without notice.
Exporter variables. An OpenTelemetry exporter setting is not known.The protocol or exporter type set in an OTEL_* variable is not known, or the Cloud gateway session that named the collector ended.