jq: JSON Processing in the Command Line

jq is a lightweight, flexible JSON processor for the command line.

Basic Filtering

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

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

# Get nested field
echo '{"user":{"email":"alice@example.com"}}' | jq '.user.email'

# Get array element
echo '[1,2,3]' | jq '.[1]'
# Output: 2

# Array slice
echo '[1,2,3,4,5]' | jq '.[2:4]'
# Output: [3,4]

Array Operations

# Get all elements
curl https://api.example.com/users | jq '.[]'

# Map over array
curl https://api.example.com/users | jq '[.[] | {id, name, email}]'

# Filter array
curl https://api.example.com/users | jq '[.[] | select(.active == true)]'

# Get array length
curl https://api.example.com/users | jq 'length'

# First/last element
curl https://api.example.com/users | jq 'first, last'

Transformations

# Build new object
echo '{"first":"John","last":"Doe"}' | jq '{fullName: (.first + " " + .last)}'

# Add field
echo '{"name":"Alice"}' | jq '. + {role: "admin"}'

# Remove field
echo '{"name":"Alice","password":"secret"}' | jq 'del(.password)'

# Rename field
echo '{"user_name":"alice"}' | jq '{username: .user_name}'

String Operations

# String interpolation
echo '{"name":"World"}' | jq '"Hello, (.name)!"'

# Split/join
echo '"a,b,c"' | jq 'split(",")'
echo '["a","b","c"]' | jq 'join(",")'

# String tests
echo '{"url":"https://api.example.com"}' | jq 'select(.url | startswith("https"))'

Real-World Examples

# Extract Docker image names
docker ps --format '{{json .}}' | jq -r '.Image'

# Parse AWS CLI output
aws ec2 describe-instances | jq -r '.Reservations[].Instances[] | [.InstanceId, .State.Name] | @tsv'

# Process GitHub API
curl https://api.github.com/repos/owner/repo/releases | jq -r '.[0] | {tag: .tag_name, date: .published_at}'

# Parse Kubernetes pods
kubectl get pods -o json | jq -r '.items[] | select(.status.phase != "Running") | .metadata.name'

Variables and Functions

# Define variable
echo '5' | jq '. as $x | $x * $x'

# Reduce
echo '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'
# Output: 15

# Group by
echo '[{"type":"a","val":1},{"type":"b","val":2},{"type":"a","val":3}]' | jq 'group_by(.type)'

jq transforms complex API responses into exactly the data you need.