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.
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.
At a Glance
| Question | Answer |
|---|---|
| Can you use it? | ✅ Yes. claude -, or send the prompt on stdin. |
| Can you change it? | ✅ Yes. Flags set the output and input format, budget, schema, and permission handling. |
| Can you turn it on or off? | - turns it on. -- strips extras. -- saves nothing. |
| Where does it live? | Flags on the claude command. Sessions still save to ~/. unless you turn that off. |
| Status | Documented Undocumented |
Print Mode Flags
Source: Run Claude Code Programmatically, CLI Reference, and claude --help.
The full flag list is on CLI Flags.
| Flag | Status | What It Does | Notes |
|---|---|---|---|
- | Documented | Prints the answer and exits. | Skips the trust dialog. |
-- | Documented | Sets the output. | text (default), json (one result object), or stream- (one JSON object per line, live). |
-- | Documented | Sets the input. | text (default) or stream- (live input, and control requests). |
-- | Documented | Adds partial message chunks as the answer grows. | Needs --. Adds stream_ lines. |
-- | Documented | Adds hook lifecycle events to the stream. | Needs --. |
-- | Documented | Adds subagent text and thinking to the stream. | Messages carry parent_. Needs stream- output. |
-- | Documented | Sends user messages from stdin back on stdout as an acknowledgment. | Needs both stream- formats. |
-- | Documented | Checks the final answer against a JSON Schema. | Pass the schema as a JSON string. |
-- | Documented | Stops at a spend limit in dollars. | Print mode only. |
-- | Documented | Turns on prompt suggestions. | Print mode sends a prompt_ message after each turn. |
-- | Documented | Says who answers permission prompts. | host (the SDK host or --) or none (anything that would prompt is denied; the permission mode decides the rest). |
-- | Documented | Saves nothing to disk. | The session cannot be resumed. Print mode only. |
-- | Documented | Starts with a minimal setup. | Skips hooks, LSP, plugin sync, attribution, auto memory, background prefetches, keychain reads, and CLAUDE. discovery. |
-- | Documented | Removes the tools that run code and Web, and ignores user, project, and local settings. | Good for untrusted input. |
--, --, -- | Documented | Choose which tools run without a prompt, which are blocked, and which exist. | See CLI Flags. |
-- | Documented | Names models to try when the main model is overloaded or not available. | See Models. |
--, --, --, -- | Documented | Pick, branch, or name the session. | See Sessions and Storage. |
--, -- | Documented | Load MCP servers for this run. | 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
| Page | What It Covers |
|---|---|
| Stream JSON Messages | Every message type that print mode writes |
| Control Protocol | Every control request a host can send on the same stream |