Getting started
Introduction
jq filters JSON on the command line: pick fields, reshape objects, and reformat output. This sheet covers the filters and flags used most often.
- jq manual (jqlang.org)
- GitHub repository (github.com)
The input
{
"account": { "plan": "pro", "seats": 3 },
"users": [
{ "name": "Ada", "role": "admin", "active": true },
{ "name": "Linus", "role": "dev", "active": false },
{ "name": "Grace", "role": "dev", "active": true }
]
}
Examples read this file as api.json.
See: Invoking jq
Field access
jq '.users[0].name' api.json
# → "Ada"
. is the input document; .foo reads a key. Strings keep their quotes
unless -r is passed.
Raw and compact output
jq -c '.users[1]' api.json
# → {"name":"Linus","role":"dev","active":false}
Flags
| Flag | Effect |
|---|---|
-r | raw strings, no quotes |
-c | one line per value |
-S | sort keys |
--tab | indent with tabs |
--indent 4 | indent with 4 spaces |
-e | exit 1 on false/null, 4 if empty |
See: Invoking jq
Selecting
Nested fields
jq -r '.account.plan' api.json
# → pro
Chain keys to walk deeper. A missing key yields null, not an error.
Arrays and slices
jq -c '.users[0:2] | map(.name)' api.json
# → ["Ada","Linus"]
.[0] is the first element and .[-1] the last; .[2:] runs to the end.
See: Array/string slice
Iteration
jq -r '.users[].name' api.json
# → Ada
# → Linus
# → Grace
.[] streams each element. Wrap the filter in brackets to collect the
stream back into an array: [.users[].name].
Optional access
jq '.users[] | .tags[]?' api.json
# → no output
? suppresses the error, so a missing tags key yields nothing instead of
aborting the run.
See: Optional operator
Filtering
select
jq -r '.users[] | select(.active).name' api.json
# → Ada
# → Grace
select(f) passes the input through only when f is true. Swap in any test,
such as select(.role == "dev").
See: select
map
jq -c '.users | map(.name)' api.json
# → ["Ada","Linus","Grace"]
map(f) applies f to every element and returns an array.
See: map
map_values
echo '{"ada":2,"linus":5}' | jq -c 'map_values(. + 1)'
# → {"ada":3,"linus":6}
On objects map_values keeps the keys; on arrays it behaves like map.
See: map_values
Keys and counts
jq -c '.users | length, (.[0] | keys)' api.json
# → 3
# → ["active","name","role"]
has("users") tests for one key. length also counts characters in a
string and keys in an object.
See: keys
Totals
echo '[12,48,7]' | jq -c '[add, min, max]'
# → [67,7,48]
add sums an array; min and max read the same array.
See: add
Sorting and grouping
sort_by
jq -c '.users | sort_by(.name) | map(.name)' api.json
# → ["Ada","Grace","Linus"]
Plain sort compares whole values; sort_by(.key) sorts objects by one
field.
See: sort_by
group_by
jq -c '.users|group_by(.role)|map([.[0].role,length])' api.json
# → [["admin",1],["dev",2]]
Groups are sorted by key. Each group is an array, so length counts its
members.
See: group_by
unique
jq -c '[.users[].role] | unique' api.json
# → ["admin","dev"]
unique_by(.key) dedupes objects by one field instead of the whole value.
See: unique
Building values
Objects and arrays
jq -c '.users[0] | {name, active}' api.json
# → {"name":"Ada","active":true}
{name} is shorthand for {name: .name}. [...] collects a stream into an
array.
See: Object construction
String interpolation
jq -r '.users[] | "\(.name) is \(.role)"' api.json
# → Ada is admin
# → Linus is dev
# → Grace is dev
\(...) interpolates any filter into a string; pair it with -r to drop the
quotes.
See: String interpolation
Conditionals
jq -r '.users[] | if .active then "in" else "out" end' api.json
# → in
# → out
# → in
Add elif .role == "admin" between if and else for more branches. end
is required.
See: if-then-else
Alternatives
echo '{"nick":null,"name":"Ada"}' | jq -r '.nick // .name'
# → Ada
// yields the right side when the left is false or null.
See: Alternative operator
Errors
jq -r '.users[0] | try (.name - 1) catch .' api.json
# → string ("Ada") and number (1) cannot be subtracted
catch . receives the message. ? is shorthand for try.
See: try-catch
Transforming
Entries
echo '{"ada":2,"linus":5}' | jq -c 'to_entries'
# → [{"key":"ada","value":2},{"key":"linus","value":5}]
with_entries
echo '{"ada":2,"linus":5}' | jq -c 'with_entries(.value += 1)'
# → {"ada":3,"linus":6}
with_entries(f) is to_entries | map(f) | from_entries.
See: to_entries
reduce
echo '[12,48,7]' | jq 'reduce .[] as $n (0; . + $n)'
# → 67
(0; . + $n) seeds the accumulator at 0 and adds each element.
See: reduce
Arguments
jq -n -c --arg name Ada --argjson n 2 '{name: $name, n: $n}'
# → {"name":"Ada","n":2}
--arg always makes a string, --argjson parses JSON. --slurpfile v f.json reads a file into $v; --rawfile v f.txt reads plain text.
See: Invoking jq
Output formats
CSV and TSV
CSV
jq -r '.users[] | [.name,.role] | @csv' api.json
# → "Ada","admin"
# → "Linus","dev"
# → "Grace","dev"
TSV
jq -r '.users[] | [.name,.role] | @tsv' api.json
# → Ada admin
# → Linus dev
# → Grace dev
@csv quotes strings and separates fields with commas; @tsv uses tabs.
See: Format strings
JSON and Base64
JSON text
jq -r '.users[0] | @json' api.json
# → {"name":"Ada","role":"admin","active":true}
Base64
jq -r '.users[0].name | @base64' api.json
# → QWRh
@base64d decodes, and @text stringifies any value.
See: Format strings
Generating JSON
jq -n -c --arg user Ada '{user: $user, admin: false}'
# → {"user":"Ada","admin":false}
-n runs the filter once with no input, so args and constants build the
document. Use inputs to read stdin from inside the program.
See: Invoking jq
Files and streams
Multiple files
# a.json = {"a":1}
# b.json = {"b":2}
jq -cs 'add' a.json b.json
# → {"a":1,"b":2}
Without -s, each value in each file is processed on its own.
See: Invoking jq
JSON Lines
# events.jsonl = {"user":"ada","ms":12}
# {"user":"linus","ms":48}
jq -c '.ms' events.jsonl
# → 12
# → 48
Slurping
jq -cs 'map(.ms) | add' events.jsonl
# → 60
JSON Lines files parse as one value per line; -s collects them into one
array.
See: Invoking jq
Streaming
echo '{"a":[{"b":1}]}' | jq -c --stream 'select(length == 2)'
# → [["a",0,"b"],1]
--stream emits [path, leaf] pairs as the input parses, keeping memory flat
on large files.
See: Streaming
0 Comments for this cheatsheet. Write yours!