Use --output-format json for Structured Output in Scripts and Pipelines

When you're using Claude Code in a script or pipeline, plain text output is hard to parse reliably. JSON output gives you structured data you can feed into jq, pipe to another tool, or process programmatically.

claude -p "list the public functions in src/auth.ts" --output-format json

Instead of freeform text, you get a JSON object with the response content, model info, token usage, and session metadata — all machine-parseable.

This unlocks automation patterns that plain text can't support:

# Extract just the response text
claude -p "summarize this file" --output-format json | jq -r '.result'

# Get token usage for cost tracking
claude -p "review this PR" --output-format json | jq '.usage'

# Chain Claude's output into another command
claude -p "list files that need tests" --output-format json \
  | jq -r '.result' \
  | xargs -I {} claude -p "write tests for {}"

Combine it with -p and stdin piping for powerful one-liners:

# Automated code review that outputs structured results
git diff main | claude -p "review this diff, output issues as JSON array" \
  --output-format json | jq '.result' | jq '.[].severity'

# Generate a changelog entry from recent commits
git log --oneline -10 | claude -p "write a changelog entry" \
  --output-format json | jq -r '.result' >> CHANGELOG.md

The stream-json variant streams output tokens as they arrive, useful for long-running tasks where you want incremental progress.

Plain text is for humans. JSON output is for machines — use --output-format json when Claude is part of a pipeline, not the endpoint.

via Claude Code