jq Cheat Sheet 2026: JSON Processing for DevOps

A quick reference for jq — the command-line JSON processor. Bookmark this page.

Basic Usage

# Pretty print JSON
echo '{"name":"Alice","age":30}' | jq .

# Read from file
jq . data.json

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

Selecting Fields

# Get a single field
echo '{"name":"Alice","age":30}' | jq '.name'
# Output: "Alice"

# Get nested field
echo '{"user":{"name":"Alice"}}' | jq '.user.name'

# Get raw string (no quotes)
echo '{"name":"Alice"}' | jq -r '.name'
# Output: Alice

# Multiple fields
echo '{"name":"Alice","age":30,"city":"Amsterdam"}' | jq '{name, city}'

Arrays

# Get all elements
echo '[1,2,3,4,5]' | jq '.[]'

# Get by index
echo '["a","b","c"]' | jq '.[0]'     # "a"
echo '["a","b","c"]' | jq '.[-1]'    # "c" (last)

# Slice
echo '[1,2,3,4,5]' | jq '.[2:4]'    # [3,4]

# Length
echo '[1,2,3]' | jq 'length'         # 3

# Array of objects — get field from each
echo '[{"name":"Alice"},{"name":"Bob"}]' | jq '.[].name'
echo '[{"name":"Alice"},{"name":"Bob"}]' | jq '[.[].name]'  # As array

Filtering

# Select objects matching condition
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | jq '.[] | select(.age > 28)'

# Multiple conditions
jq '.[] | select(.status == "active" and .role == "admin")'

# Contains
jq '.[] | select(.name | contains("Ali"))'

# Map and filter
jq '[.[] | select(.age > 25) | .name]'

Transformation

# Map (transform each element)
echo '[1,2,3]' | jq '[.[] * 2]'       # [2,4,6]
echo '[{"a":1},{"a":2}]' | jq '[.[].a]'  # [1,2]

# Add new fields
jq '.[] | . + {"status": "active"}'

# Rename fields
jq '{username: .name, years: .age}'

# Group by
jq 'group_by(.category) | map({key: .[0].category, count: length})'

# Sort
jq 'sort_by(.age)'
jq 'sort_by(.name) | reverse'

# Unique
jq '[.[].category] | unique'

String Operations

# String interpolation
jq -r '"Name: \(.name), Age: \(.age)"'

# Split and join
echo '"hello-world"' | jq 'split("-")'     # ["hello","world"]
echo '["a","b","c"]' | jq 'join(",")'      # "a,b,c"

# Uppercase/lowercase
echo '"hello"' | jq 'ascii_upcase'         # "HELLO"

# Regex match
echo '"abc123"' | jq 'test("[0-9]+")'      # true
echo '"2026-04-12"' | jq 'capture("(?<y>[0-9]{4})-(?<m>[0-9]{2})")'

Aggregation

# Count
jq 'length'
jq '[.[] | select(.active)] | length'

# Sum
echo '[{"price":10},{"price":20}]' | jq '[.[].price] | add'  # 30

# Min/Max
echo '[3,1,4,1,5]' | jq 'min'     # 1
echo '[3,1,4,1,5]' | jq 'max'     # 5

# Reduce
jq 'reduce .[] as $item (0; . + $item.price)'

Practical Patterns

# kubectl + jq
kubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'

# Parse nested API response
curl -s https://api.github.com/repos/kubernetes/kubernetes | \
  jq '{stars: .stargazers_count, forks: .forks_count, language: .language}'

# Convert JSON to CSV
jq -r '.[] | [.name, .email, .age] | @csv'

# Merge two JSON files
jq -s '.[0] * .[1]' file1.json file2.json

Tips and Tricks

• Use -r for raw output (no quotes around strings)
• Use -e to set exit code based on output (useful in scripts)
• Use --arg name value to pass shell variables into jq
• Use @base64 / @base64d for encoding/decoding
• Use env.VAR_NAME to access environment variables

Related Resources

• curl Cheat Sheet
• Bash Cheat Sheet
• YAML Cheat Sheet