jq

2026-03-27 3 minute read 0 Comments #command line | #linux | #json | #api

Summary

jq is a command-line JSON processor. Where awk rules over whitespace-delimited text, jq rules over JSON — the lingua franca of every REST API, AI service, and cloud platform. Pass it JSON from stdin or a file, write a filter expression, and get structured output back.

Install on Debian/Ubuntu:

sudo apt-get install jq

Install on macOS:

brew install jq

Usage

jq '<filter>' [file]

Without a file, jq reads from stdin — perfect for piping curl output directly.

Examples

Pretty-print JSON

curl -s https://api.example.com/users | jq .

The . filter is the identity — it just reformats the input with syntax highlighting and indentation.

Extract a field

echo '{"name": "Alice", "age": 30}' | jq '.name'
"Alice"

Extract a nested field

echo '{"user": {"id": 42, "email": "alice@example.com"}}' | jq '.user.email'
"alice@example.com"

Iterate over an array

echo '[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]' | jq '.[] | .name'
"Alice"
"Bob"

Build a new object from selected fields

curl -s https://api.example.com/users \
  | jq '[.[] | {id: .id, email: .email}]'

Filter an array by condition

# Show only users where active is true
jq '[.[] | select(.active == true)]' users.json

Extract raw strings (strip quotes)

jq -r '.token' response.json

-r outputs raw strings without JSON quoting — useful when piping values to other commands.

Use jq output in a shell loop

for id in $(jq -r '.[].id' users.json); do
  echo "Processing user $id"
done

Construct a JSON payload for an API call

jq -n --arg model "claude-opus-4-6" --arg prompt "Explain awk in one sentence" \
  '{"model": $model, "messages": [{"role": "user", "content": $prompt}]}'

-n produces output without reading input; --arg injects shell variables safely.

Parse an AI API response

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":256,"messages":[{"role":"user","content":"Hello"}]}' \
  | jq -r '.content[0].text'

Slurp multiple JSON lines into an array

# Many APIs return newline-delimited JSON (ndjson); --slurp wraps them in an array
jq -s '.' stream.ndjson

Combine with grep for quick audits

cat access.log | grep 'POST /api' | jq -r '.user_id' | sort | uniq -c | sort -rn | head -10

Common Flags

Flag	Meaning
`.`	Identity — pretty-print input
`-r`	Raw string output (no quotes)
`-c`	Compact output (single line)
`-n`	Null input — build JSON from scratch
`-s`	Slurp — read all input into one array
`--arg key val`	Bind a shell variable for use in the filter
`--argjson key val`	Bind a JSON-typed variable

jq