# Print Mode Output Flags

> How to shape what claude -p prints for a script: text, JSON or a stream of events. Then a fixed JSON shape, and caps on the turns and dollars of a run.

**Course:** [Claude Code Commands](https://learn.benibix.com/learn/ai-claude-code-commands)  
**Time:** 12 min

**After this lesson you can:**

- Pick text, json or stream-json output
- Make a run end with JSON in a set shape
- Cap a run by turns and by dollars

## How to make claude -p print what a program can read

claude -p runs one task and prints the answer, with no chat. --output-format sets the shape. text, the default, prints just the answer. json prints one object at the end with the answer, the session ID and the cost. stream-json prints one JSON line per event as it happens, so a program can follow the run live.

--json-schema makes the run end with JSON in a shape you set. You pass a JSON Schema: the fields you want and their types. Claude does the task first, then puts an answer that fits into the structured_output field. If the schema itself is broken, Claude Code stops with an error.

Two limits keep a run from going on forever. --max-turns caps how many turns it may take. A turn is one round where Claude acts, then reads what came back. There is no cap unless you set one. --max-budget-usd stops the run once spend reaches a dollar amount, and subagents count too.

That spend is Claude Code's own estimate, so it can differ from your bill. A step already running can take the total past the cap, so leave room. --no-session-persistence saves nothing to disk, so the run cannot be resumed. Use it for a run on text you do not want kept.

--input-format stream-json goes the other way. It reads one JSON message per line. That way a program can keep feeding the same run. Use it with --output-format stream-json. --replay-user-messages sends each message back once it is taken, so the program knows it got there.

Four flags add more lines to a stream-json run. --include-partial-messages sends the answer in bits as it is written. --include-hook-events adds what your hooks did. --forward-subagent-text adds what helpers write. --prompt-suggestions adds a guess at your next prompt. An app can show it as a button.

--verbose shows the full output of every turn, not the short view. In a chat you see each tool call and its result in full. In a -p run, stream-json output needs it, which is why it appears in almost every stream example. It beats the viewMode setting for this session.

## The three output shapes

| --output-format | What prints | Who reads it |
| --- | --- | --- |
| text | The answer only | A person |
| json | One object at the end | A script |
| stream-json | One line per event | An app that shows the run live |

```bash
claude -p "Summarize this project" --output-format json

claude -p --max-turns 3 --max-budget-usd 5 "Fix the typo in README.md"

claude -p --output-format stream-json --verbose \
  --include-partial-messages "Explain recursion"
```
One JSON object at the end, then a run capped by turns and dollars. Last, a live stream that shows the words as they are written.

![One answer in three shapes. text: The tests pass. I fixed the date check. json: one object with result, session_id and total_cost_usd 0.04. stream-json: three lines, a system init event, an assistant message and a result. A note says text is for people, and json and stream-json are for programs.](https://learn.benibix.com/diagrams/flag-output-format.svg)

### Example: Emma's nightly report reads one field

Emma's script runs claude -p every night to sum up new issues. It used to scrape the text, and it broke whenever the wording changed.

Now it passes --json-schema with 2 fields, count and summary, and reads structured_output. With --max-budget-usd 2, a bad night costs about 2 dollars at most.

**Words in this lesson:** [--output-format Flag](https://learn.benibix.com/term/ai/output-format-flag), [--json-schema Flag](https://learn.benibix.com/term/ai/json-schema-flag), [JSON Schema](https://learn.benibix.com/term/development/json-schema), [--max-turns Flag](https://learn.benibix.com/term/ai/max-turns-flag), [--max-budget-usd Flag](https://learn.benibix.com/term/ai/max-budget-usd-flag), [--no-session-persistence Flag](https://learn.benibix.com/term/ai/no-session-persistence-flag), [--input-format Flag](https://learn.benibix.com/term/ai/input-format-flag), [--include-partial-messages Flag](https://learn.benibix.com/term/ai/include-partial-messages-flag), [--include-hook-events Flag](https://learn.benibix.com/term/ai/include-hook-events-flag), [--forward-subagent-text Flag](https://learn.benibix.com/term/ai/forward-subagent-text-flag), [--prompt-suggestions Flag](https://learn.benibix.com/term/ai/prompt-suggestions-flag), [--verbose Flag](https://learn.benibix.com/term/ai/verbose-flag)

**Question:** Which flag makes claude -p end with an answer in fields you chose?

**Answer:** --json-schema. --json-schema takes the fields and their types. Claude does the task, then puts an answer that fits into structured_output.

---

Source: https://learn.benibix.com/learn/ai-claude-code-commands/print-mode-output-flags
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
