Print Mode Output Flags
Level 5 · Scripts and servers
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 contentsLesson 14 of 17
Level 1 · Get started
Level 2 · Inside a conversation
Level 3 · Parallel work and review
Level 4 · Setup and extensions
Level 5 · Scripts and servers
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
12 mincovers 12 glossary entries
Worth reading first: The claude plugin Commands
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 |
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"Worked 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.
The words for this lesson12
Check yourself
Which flag makes claude -p end with an answer in fields you chose?
Finished this lesson?
Marking it complete also marks its 12 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.