When you run Claude Code headless, you can decide how the result comes back. The --output-format flag gives you three choices, each suited to a different job.
text
The default is text: plain output meant for a human to read. This is what you get when you do not pass the flag at all.
claude -p "summarize this repo" --output-format text
Use it for quick questions where you just want to read the answer in your terminal.
json
Pass json and the result comes back as a single structured object once the run finishes. That structure is what makes automation reliable: your script can parse the output instead of guessing where the answer starts and ends.
claude -p "list the API routes" --output-format json
This is the basis for CI and scripting. A step in a pipeline can read the JSON, pull out the field it needs, and pass it on.
stream-json
The stream-json format emits structured events as they happen rather than waiting for the end. It suits long-running tasks where you want to watch progress or process pieces as they arrive.
claude -p "refactor the auth module" --output-format stream-json
Picking one
Use text when a person reads the output. Use json when a program reads it and only needs the final result. Use stream-json when a program reads it but wants the events as they come. In short: text for you, json for scripts, stream-json for scripts that care about progress.
Comments
Be the first to comment.