jq Cheat Sheet: Filter, Transform, and Query JSON from the Terminal

Quick reference tables

Basic filters

Pipe and comma

Type and value checks

Constructing output

Select and conditionals

Array operations

String operations

Math and comparison

Path operations

Reduce and advanced

CLI flags

Detailed sections

Common DevOps patterns

These are the jq one-liners you end up writing constantly in real DevOps work.

Extract a single field:

curl -s https://api.example.com/health | jq '.status'
# "ok"

# Without quotes
curl -s https://api.example.com/health | jq -r '.status'
# ok

List all keys of an object:

echo '{"name":"web","port":3000,"env":"prod"}' | jq 'keys'
# ["env","name","port"]

Filter array elements:

# Get all services where status is "running"
kubectl get pods -o json | jq '.items[] | select(.status.phase == "Running") | .metadata.name'

Reshape: extract specific fields from array of objects:

docker ps --format json | jq -r '[.Names, .Image, .Status] | @tsv'

Count elements:

cat data.json | jq '.users | length'

Build a new object from parts:

cat server.json | jq '{host: .ip, port: .config.port, secure: (.config.tls // false)}'

Default values:

# Use "unknown" if .region is null or missing
cat data.json | jq '.region // "unknown"'

Sort and deduplicate:

cat data.json | jq '[.[] | .tags[]] | unique | sort'

AWS CLI workflows

jq is the standard way to extract data from AWS CLI JSON output.

# List all EC2 instance IDs and their state
aws ec2 describe-instances | jq -r '.Reservations[].Instances[] | [.InstanceId, .State.Name] | @tsv'

# Get all running instance IPs
aws ec2 describe-instances \
  --filters "Name=instance-state-name,Values=running" | \
  jq -r '.Reservations[].Instances[].PublicIpAddress'

# Get all S3 bucket names
aws s3api list-buckets | jq -r '.Buckets[].Name'

# Get a specific secret value from Secrets Manager
aws secretsmanager get-secret-value --secret-id myapp/prod | \
  jq -r '.SecretString | fromjson | .DB_PASSWORD'

# Get the latest AMI ID from a list
aws ec2 describe-images --owners amazon \
  --filters 'Name=name,Values=amzn2-ami-hvm-*' | \
  jq -r '.Images | sort_by(.CreationDate) | last | .ImageId'

Kubernetes workflows

# Get all pod names in a namespace
kubectl get pods -n default -o json | jq -r '.items[].metadata.name'

# Get pods that are NOT in Running state
kubectl get pods -o json | jq -r '.items[] | select(.status.phase != "Running") | .metadata.name'

# Get all container images in use across pods
kubectl get pods --all-namespaces -o json | \
  jq -r '.items[].spec.containers[].image' | sort | uniq

# Get resource limits for all containers
kubectl get pods -o json | jq '.items[] | {
  pod: .metadata.name,
  containers: [.spec.containers[] | {
    name: .name,
    cpu: .resources.limits.cpu,
    memory: .resources.limits.memory
  }]
}'

# Get all nodes and their roles
kubectl get nodes -o json | \
  jq -r '.items[] | [.metadata.name, (.metadata.labels | to_entries | map(select(.key | startswith("node-role"))) | map(.key) | join(","))] | @tsv'

Docker and compose workflows

# List running container names and images
docker ps --format '{{json .}}' | jq -r '[.Names, .Image] | @tsv'

# Inspect a container's environment variables
docker inspect mycontainer | jq '.[0].Config.Env[]'

# Get all exposed ports for a container
docker inspect mycontainer | jq '.[0].NetworkSettings.Ports'

# Get all container IPs on a specific network
docker network inspect mynetwork | jq '.[0].Containers | to_entries[] | {name: .value.Name, ip: .value.IPv4Address}'

Using variables in filters

Shell variables can be passed into jq filters safely — no string interpolation needed.

# Using --arg (passes as JSON string)
TARGET_ENV="production"
cat config.json | jq --arg env "$TARGET_ENV" '.environments[] | select(.name == $env)'

# Using --argjson (passes as raw JSON — number, array, object, bool)
THRESHOLD=100
cat metrics.json | jq --argjson thresh "$THRESHOLD" '.[] | select(.value > $thresh)'

# Multiple variables
cat data.json | jq --arg name "alice" --arg role "admin" \
  '.users[] | select(.name == $name and .role == $role)'

Reduce — accumulating results

# Sum all values in an array
echo '[1, 2, 3, 4, 5]' | jq 'reduce .[] as $x (0; . + $x)'
# 15

# Group objects by a field into a map
echo '[{"type":"A","v":1},{"type":"B","v":2},{"type":"A","v":3}]' | \
  jq 'reduce .[] as $x ({}; .[$x.type] += [$x.v])'
# {"A":[1,3],"B":[2]}

# Count occurrences of each value
cat logs.json | jq '[.[].status] | reduce .[] as $s ({}; .[$s|tostring] += 1)'

Processing line-delimited JSON (NDJSON / JSONL)

Many logging tools (CloudWatch, Loki, Fluentd) output one JSON object per line rather than a JSON array.

# Process each line as a separate JSON object
cat logs.ndjson | jq -r '.message'

# Collect all lines into an array, then filter
cat logs.ndjson | jq -s '[.[] | select(.level == "error")]'

# Count errors
cat logs.ndjson | jq -s '[.[] | select(.level == "error")] | length'

Processing raw text input

Use -R to read non-JSON input, then parse with fromjson if needed.

# Count lines in a file
cat file.txt | jq -Rn '[inputs] | length'

# Convert CSV-ish output to JSON (simple case)
df -h | tail -n +2 | jq -Rn '
  [inputs | split(" ") | map(select(. != "")) | {
    filesystem: .[0],
    size: .[1],
    used: .[2],
    avail: .[3],
    use_pct: .[4],
    mount: .[5]
  }]
'

Related: Linux Bash Cheat Sheet | Docker Compose Cheat Sheet | Nginx Cheat Sheet

System_Continuity

Next_Recommended_Node

Docker Compose Cheat Sheet: Services, Volumes, Networks & Production Patterns

Complete Docker Compose reference — service definitions, volumes, networks, environment variables, health checks, overrides, and production-ready compose file templates.

Cobie

5m read

Cheatsheet 5m

Nginx Cheat Sheet: Config, Routing, SSL & Performance

Log_Access

Cheatsheet 5m

tmux Cheat Sheet: Sessions, Panes, Windows & Config

Log_Access

Browse the full manifest