--output-format
Claude CodeDefinition
A Claude Code CLI flag that controls the response format. Values: 'text' (default, plain text), 'json' (structured JSON), 'stream-json' (streaming JSON events). Use with --json-schema to guarantee output matches a specific schema. Critical for CI/CD pipeline integration.
Example Usage
claude -p 'Analyze dependencies' --output-format json --json-schema ./schema.json to get machine-parseable output in pipelines.
Why It Matters for the CCA-F Exam
Exam questions pair this flag with `--print` and `--json-schema` in CI/CD scenarios. Candidates must be able to (1) match the right format value to a described use case and (2) distinguish `--output-format` (structure of the response envelope) from `--json-schema` (schema the output content must conform to).
In Depth
The --output-format flag controls the serialization format of Claude Code's response when running in non-interactive mode (i.e., alongside -p / --print). Three values are available:
text(default) — plain prose, suitable for human-readable logs and terminal output. When piped to a file, it reads like a normal document.json— emits a single JSON object containing the complete response once the model finishes. The object includes the assistant's message content and metadata. Downstream tooling can parse this withjqor any JSON library without needing to strip ANSI codes or handle streaming state.stream-json— emits newline-delimited JSON (NDJSON) events as the model generates tokens. Each line is a self-contained JSON object representing a delta or lifecycle event. This is the right choice when you want to stream progress into a UI, pipe through a live-updating dashboard, or process the response incrementally rather than waiting for the full answer.
Choosing the wrong format is a common source of CI/CD fragility. A pipeline that parses text output with regex breaks the moment the model rephrases its answer. Switching to json makes the contract explicit: the shape is stable and machine-readable regardless of how the model words the prose inside it.
The flag becomes especially powerful when combined with --json-schema. Together they form a two-part guarantee: --output-format json says "give me JSON," and --json-schema ./schema.json says "give me JSON that matches this exact schema." This is the recommended pattern for any pipeline step that feeds Claude Code output into a database, a dashboard, or another automated process.
| Format | Output shape | Suitable for |
|---|---|---|
text | Plain prose string | Human review, logs, summaries |
json | Single JSON object (complete) | Structured pipelines, database writes |
stream-json | NDJSON event stream | Live UI updates, incremental processing |
In Claude Code's CI/CD integration context, --output-format json paired with --print is the canonical pattern for producing parseable artifacts from a model invocation. The structured envelope lets downstream steps extract specific fields — confidence scores, action lists, file paths — without string-matching prose output.
For the exam, be ready to select the right format for a given scenario. A GitHub Actions step that uploads results to an analytics API wants json. A step that displays a summary in a PR comment might use text. A step that feeds a real-time progress indicator wants stream-json. The CI/CD Structured Output & Incremental Reviews concept covers how these formats compose in multi-step pipelines, which is a recurring exam topic.
How It Compares
| Flag value | Response delivery | Machine-parseable | Supports --json-schema | Best for |
|---|---|---|---|---|
text | Full response at once | No | No | Human-readable logs |
json | Full response at once | Yes | Yes | Pipeline steps, DB writes |
stream-json | Incremental NDJSON events | Yes (per event) | Limited | Live UIs, streaming dashboards |
Frequently Asked Questions
Does --output-format work without --print?
In interactive mode `--output-format` has no meaningful effect because the response is rendered in the terminal UI, not written to stdout in a structured form. The flag is only useful in non-interactive (`--print`) mode where stdout is consumed by a downstream process.
What does the json envelope look like?
The exact schema may evolve, but the envelope typically contains the assistant's response content (as a string or structured content blocks) plus metadata like token counts. The safest approach for production pipelines is to pair `--output-format json` with `--json-schema` so that the fields your pipeline reads are explicitly guaranteed by the schema.
When should I use stream-json vs json?
Use `stream-json` when your consumer can process incremental events — for example, a web UI that wants to stream text to the user as it arrives, or a monitoring agent that logs progress events in real time. Use `json` when your consumer needs the complete, final response before proceeding, such as a database write step or a downstream model call that uses Claude's full output as input.