Skip to content
BENIBIX Learn

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

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-formatWhat printsWho reads it
textThe answer onlyA person
jsonOne object at the endA script
stream-jsonOne line per eventAn 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, three shapes.

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.