Process JSON in the Terminal with jq

The jq command is one of the fastest ways to inspect and transform JSON directly in your shell. It pretty-prints by default and gives you a compact filter language for selecting and reshaping data.

Basic example:

echo '{"firstName": "John", "lastName": "Doe", "roles": ["admin", "editor"]}' | jq

Output:

{
  "firstName": "John",
  "lastName": "Doe",
  "roles": [
    "admin",
    "editor"
  ]
}

Read one field:

echo '{"firstName": "John", "lastName": "Doe", "roles": ["admin", "editor"]}' | jq '.roles[0]'

Output:

"admin"

1) Sanitizing Strings

echo "$OUTPUT" | jq -Rsa .

• -R: do not parse as JSON, treat input as raw text
• -s: read all lines into one string
• -a: force ASCII output and escape non-ASCII characters

This is useful when you need safe JSON encoding of multiline shell output.

2) Stringifying JSON

jq '. | tojson'

From jq docs: tojson serializes a value as JSON text, while fromjson parses JSON text into structured data.

More Useful jq Snippets

Compact single-line JSON:

jq -c . data.json

Print only top-level keys:

jq 'keys' data.json

Select and rename nested fields:

jq '.users[] | {id, email: .profile.email, city: .profile.address.city}' data.json

Filter production API errors from logs:

jq '.events[] | select(.level == "error" and .env == "prod")' app-log.json

Sort users by signup date:

jq 'sort_by(.createdAt) | reverse' users.json

Count failed CI jobs:

jq '[.jobs[] | select(.status == "failed")] | length' ci-report.json

Group orders by status:

jq 'group_by(.status) | map({status: .[0].status, count: length})' orders.json

Inject shell variable:

jq --arg env "$ENV" '.environment = $env' data.json

Merge JSON files (override pattern):

jq -s '.[0] * .[1]' base.json override.json

Export JSON to CSV:

jq -r '.[] | [.id, .name, .email] | @csv' users.json

Create a quick Markdown report from JSON:

jq -r '.services[] | "- **\(.name)**: \(.uptime)% uptime"' status.json

Find secrets accidentally committed (simple heuristic):

jq '.. | strings | select(test("AKIA|SECRET|TOKEN"; "i"))' dump.json

These patterns cover most practical command-line workflows: inspect, filter, reshape, merge, and export.