jq Cheat Sheet: 40 Commands for Filtering and Transforming JSON

Quick answer: jq is a command-line JSON processor. The five filters that cover most daily work are .key to read a field, .[] to iterate an array, select(condition) to filter, map(filter) to transform every element, and the -r flag to print strings without quotes. Chain them with |: jq -r '.[] | select(.active) | .email' users.json prints the email of every active user, one per line.

You have a 3,000-line API response in the terminal and need the IDs of every record where status is failed. Scrolling is not an option and writing a Python script feels heavy. jq does it in one line, and the forty commands below are the ones that come up again and again. Each row shows the filter, what it does, a tiny input, and the output you will see.

Run a sample expression in the JSONPath Query Tester, or explore the same nested data in the JSON Viewer.

Install jq and Try a Filter

jq is a single binary with no dependencies. Package managers carry it on every platform:

brew install jq            # macOS
sudo apt install jq        # Debian, Ubuntu
winget install jqlang.jq   # Windows
jq --version

The fastest way to learn a filter is to run it against a literal with -n, which starts from null input, so you do not need a file at all:

jq -n '[1, 2, 3] | map(. * 10) | add'
# 60

echo '{"users": [{"name": "Ada"}, {"name": "Bob"}]}' | jq -r '.users[].name'
# Ada
# Bob

How to Read This Cheat Sheet

jq works like a Unix pipeline inside a single program: each filter takes a JSON value in and emits zero or more values out, and | connects them. The command shape is always jq [flags] 'filter' [file], with input from stdin when no file is given. Flags such as -r go before the filter. Rows that start with jq show the full command because the flag is the point; the rest show only the filter.

Basics: Selecting Values

Wrap the filter in single quotes on the shell. Every example assumes the input arrives on stdin or as a file argument.

Building and Filtering

select keeps values that pass a test; map applies a filter to every element and returns a new array.

Output Flags and Formats

These are command-line flags and @format strings. -r is the one you will reach for most: without it every string output keeps its quotes.

Transforming Objects and Arrays

to_entries and with_entries are the escape hatch whenever you need to treat keys as data.

Strings and Math

jq string functions use regular expressions in the Oniguruma dialect, so most PCRE patterns work.

Conditionals and Defaults

The // operator is the fastest way to supply defaults for missing or null fields.

Variables and Shell Arguments

--arg always binds a string. Use --argjson when you need a number, boolean, or object.

Input and Output Streams

jq treats a file of concatenated values (including JSON Lines) as a stream and runs the filter once per value.

A Few Worth Knowing Beyond the Forty

• .. walks every value in the tree recursively, so [.. | numbers] collects every number anywhere in the document.
• has("key") tests for a key even when its value is null, which .key != null cannot distinguish.
• jq -n '[inputs]' does what -s does but streams, which is the form the jq manual recommends for large files.
• reduce .[] as $x (0; . + $x) is the general fold when add is not enough.
• @base64, @uri, @sh, and @json sit alongside @csv and @tsv as output formatters.
• --tab and --indent 2 control pretty-printing; -j joins raw output without newlines.

Reading JSON From curl

The most common place jq sits is immediately after curl. Use curl's -s so the progress meter does not pollute the stream:

# Pick two fields from one object
curl -s https://api.github.com/repos/jqlang/jq | jq '{name, stars: .stargazers_count}'

# Authenticated request, tab-separated output for a shell loop
curl -s -H "Authorization: Bearer $TOKEN" https://api.example.com/users \
  | jq -r '.[] | [.id, .email] | @tsv'

# Fail loudly if the response is not JSON (an HTML error page, say)
curl -s https://api.example.com/health | jq -e '.status == "ok"' > /dev/null || echo "unhealthy"

When a request needs a JSON body rather than just reading one, the sending JSON with curl guide covers headers, files, and the Windows quoting problems. For a long response where you want to look rather than script, pipe through jq . or paste it into JSON Prettifier, where the collapsible tree view and syntax highlighting make a 3,000-line payload readable.

Patterns You Will Reuse

Combinations that come up in real work, built from the rows above:

# Count records per status
jq 'group_by(.status) | map({status: .[0].status, count: length})' orders.json

# CSV with a header row
jq -r '["id","email"], (.[] | [.id, .email]) | @csv' users.json

# Records missing a required key
jq -c '.[] | select(has("email") | not)' users.json

# Rename a key everywhere
jq 'map(with_entries(if .key == "userId" then .key = "user_id" else . end))' events.json

# Convert an object of objects into an array with the key inside
jq 'to_entries | map(.value + {id: .key})' lookup.json

# Deep-merge a defaults file into each record
jq --slurpfile d defaults.json 'map($d[0] * .)' records.json

The last one uses * on objects, which merges recursively, with the right-hand side winning on conflicts. For converting between JSON arrays and one-record-per-line files, the JSON Lines guide has a dedicated table of jq commands, and the JSON to CSV guide goes deeper on @csv with nested data.

Gotchas

• Forgetting -r. NAME=$(jq '.name' f.json) stores "Ada" with the quotes. Add -r whenever the result goes to the shell.
• Cannot index array with "name". The input is an array and the filter expects an object. Put .[] or map(...) in front.
• Cannot iterate over null. .items[] ran on a record with no items key. Write .items[]? to skip silently or (.items // [])[] to default to an empty array.
• --arg is always a string. select(.age > $min) with --arg min 30 compares a number to a string and matches nothing. Use --argjson.
• Windows quoting. cmd.exe does not treat single quotes as quotes. Use double quotes and escape inner ones: jq ".[] | select(.name == \"Ada\")", or put the filter in a file and use -f filter.jq. In PowerShell, single quotes work but call jq.exe explicitly.
• Invalid input. jq stops at the first parse error with a line number. If the file came from a hand-edited config, a trailing comma is the usual culprit; the common JSON errors guide lists the rest.
• Keys with dashes or spaces. .user-id is parsed as subtraction. Write .["user-id"].