jq Cheat Sheet

Basic Syntax

.Identity (whole input)
.keyObject field
.key.nestedNested field
.[0]Array index
.[]Iterate array
.key?Optional (no error)

CLI Options

jq '.'Pretty print
-rRaw output
-cCompact output
-sSlurp (array wrap)
-nNull input
--arg k vPass string var

Array Operations

[.[]]Collect to array
.[2:5]Array slice
| lengthArray length
| firstFirst element
| lastLast element
| reverseReverse array
| sortSort array
| uniqueRemove duplicates

Object Operations

| keysGet keys
| valuesGet values
| has("key")Check key exists
| to_entriesTo [{key,value}]
| from_entriesFrom entries
| del(.key)Delete key
+ {new: "val"}Add field

Common Examples

# Get specific field from each object in array
jq '.[].name' data.json

# Filter array by condition
jq '[.[] | select(.age > 30)]' users.json

# Map/transform values
jq '[.[] | {name: .name, upper: (.name | ascii_upcase)}]'

# Get nested field with default
jq '.config.timeout // 30' config.json

# Construct new object
jq '{id: .id, fullName: "\(.firstName) \(.lastName)"}'
          

Conditionals & Logic

# If-then-else
jq 'if .status == "active" then "yes" else "no" end'

# Select (filter)
jq 'select(.price < 100)'
jq 'select(.name | contains("John"))'

# And/Or
jq 'select(.age > 18 and .status == "active")'
jq 'select(.type == "A" or .type == "B")'

# Not
jq 'select(.deleted | not)'
          

String Functions

| ascii_downcaseLowercase
| ascii_upcaseUppercase
| split(",")Split string
| join(",")Join array
| ltrimstr("pre")Remove prefix
| rtrimstr("suf")Remove suffix
| test("regex")Regex test

Math & Reduce

| addSum array
| min / maxMin/max value
| floor / ceilRound numbers
| group_by(.key)Group by field
| sort_by(.key)Sort by field
| unique_by(.key)Unique by field

Advanced Patterns

# Group and count
jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Flatten nested arrays
jq '[.[][] ]'   # or | flatten

# Recursive descent (find all "id" fields)
jq '.. | .id? // empty'

# Update nested value
jq '.config.timeout = 60'

# Pass variable from shell
jq --arg name "$NAME" '.user = $name'
          

Scan a script before you share it — free