Pretty-print JSON from stdin
Format JSON read from stdin with default pretty output.
bashANYjqpretty-printstdin
bash
echo '{"name":"alice","age":30}' | jq '.'Notes
The identity filter `.` returns the input unchanged, but jq formats it nicely.
jq Cheat Sheet
Core jq syntax, filters, selectors, arrays, objects, variables, sorting, grouping, formatting, and shell-friendly usage.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Getting Started
Basic invocation and output behavior.
bash
jq '.' data.jsonNotes
Use jq directly on a file path instead of piping with `cat`.
bash
jq -c '.' data.jsonNotes
Useful for logs, NDJSON-like processing, or piping into other tools.
bash
echo '{"name":"alice"}' | jq -r '.name'Notes
The `-r` flag is essential when you want shell-friendly plain text.
Run jq without input
Create JSON from scratch using null input mode.
bashANYjqnull-inputgenerate-json
bash
jq -n '{app: "cheatsheet", enabled: true}'Notes
`-n` starts with no input document, which is ideal for generating JSON.
bash
jq -M '.' data.jsonNotes
`-M` disables color even if your terminal supports it.
bash
jq -S '.' data.jsonNotes
Helpful for stable diffs and deterministic output.
Selectors and Paths
Pick values by key, path, and array index.
bash
echo '{"name":"alice","age":30}' | jq '.name'Notes
Returns the value of the `name` field.
bash
echo '{"user":{"profile":{"email":"a@example.com"}}}' | jq '.user.profile.email'Notes
Dot chaining walks nested objects.
bash
echo '{"user":{}}' | jq '.user.profile?.email'Notes
The `?` suppresses errors for missing fields.
bash
echo '[10,20,30]' | jq '.[1]'Notes
Array indexing is zero-based.
bash
echo '[10,20,30,40,50]' | jq '.[1:4]'Notes
This returns elements at indexes 1 through 3.
bash
echo '["a","b","c"]' | jq '.[]'Notes
`.[]` expands the array into multiple outputs.
bash
echo '{"a":1,"b":2}' | jq '.[]'Notes
On objects, `.[]` returns the values.
bash
echo '{"name":"alice"}' | jq 'has("name")'Notes
Use `has()` for existence checks before dereferencing fields.
bash
echo '{"name":"alice","age":30}' | jq 'keys'Notes
Useful for introspection and debugging unknown schemas.
bash
echo '{"user":{"name":"alice","roles":["admin"]}}' | jq 'paths'Notes
`paths` helps inspect complex or unfamiliar nested JSON structures.
Arrays and Objects
Build, reshape, merge, and inspect collections.
bash
echo '[1,2,3,4]' | jq 'length'Notes
`length` works on arrays, strings, and objects.
Map each item to a property
Transform an array of objects into one field per item.
bashANYjqmaparrays
bash
echo '[{"name":"a"},{"name":"b"}]' | jq 'map(.name)'Notes
`map()` applies a filter to each element and returns an array.
bash
echo '[1,2,3,4]' | jq 'add'Notes
`add` sums numeric arrays and can also merge arrays or strings depending on input.
bash
echo '[[1,2],[3,[4]]]' | jq 'flatten'Notes
`flatten` recursively flattens nested arrays into one array.
bash
echo '[3,1,2,3,2]' | jq 'unique'Notes
`unique` sorts and deduplicates.
bash
echo '[3,1,2]' | jq 'sort'Notes
Use `sort_by()` for arrays of objects.
bash
echo '[{"name":"b","age":20},{"name":"a","age":30}]' | jq 'sort_by(.name)'Notes
`sort_by(.field)` is common for reporting and reformatting API output.
bash
echo '[{"team":"a","name":"x"},{"team":"a","name":"y"},{"team":"b","name":"z"}]' | jq 'group_by(.team)'Notes
Input should already be sorted by the grouping field for predictable results.
bash
jq -n '{name:"alice",age:30} + {age:31,city:"SF"}'Notes
The `+` operator merges objects shallowly.
bash
echo '{"id":1,"name":"alice","email":"a@example.com"}' | jq '{id, name}'Notes
Object construction is central to jq transformations.
Filters and Conditions
Select, filter, update, and conditionally transform JSON.
Select objects matching condition
Filter array items based on a boolean expression.
bashANYjqselectfiltering
bash
echo '[{"name":"a","age":20},{"name":"b","age":35}]' | jq '.[] | select(.age >= 30)'Notes
`select()` keeps only inputs that satisfy the condition.
bash
echo '[{"name":"a","active":true},{"name":"b","active":false}]' | jq 'map(select(.active))'Notes
Wrap `select()` with `map()` when you want an array back.
bash
echo '{"name":"alice"}' | jq '.email // "unknown@example.com"'Notes
The `//` operator provides a default value.
bash
echo '{"score":85}' | jq 'if .score >= 80 then "pass" else "fail" end'Notes
jq supports full conditional branching with `if ... then ... else ... end`.
bash
echo '{"name":"alice","age":30}' | jq '.age = 31'Notes
Assignment lets you modify existing JSON structures.
bash
echo '{"count":5}' | jq '.count += 1'Notes
Arithmetic update operators work on matching scalar types.
bash
echo '{"name":"alice","password":"secret"}' | jq 'del(.password)'Notes
`del()` is useful for sanitizing secrets or noisy fields.
bash
echo '{"user":{"profile":{"ssn":"123","name":"alice"}}}' | jq 'del(.user.profile.ssn)'Notes
You can target nested paths directly inside `del()`.
bash
echo '[1,null,2,null]' | jq '.[] | select(. != null)'Notes
Use `empty` or `select()` to suppress unwanted outputs.
Variables, Reduce, and Advanced Transformations
Use variables, accumulators, and custom reshaping patterns.
bash
echo '{"user":{"name":"alice"},"team":"eng"}' | jq '.user as $u | {name: $u.name, team: .team}'Notes
The `as $var` syntax avoids repeating long paths.
bash
echo '[1,2,3,4]' | jq 'reduce .[] as $n (0; . + $n)'Notes
`reduce` is powerful for custom aggregations.
bash
echo '[{"id":1,"name":"a"},{"id":2,"name":"b"}]' | jq 'reduce .[] as $item ({}; .[$item.id|tostring] = $item.name)'Notes
This pattern is common when converting lists into keyed lookup tables.
bash
echo '{"a":1,"b":2}' | jq 'with_entries(.key |= ascii_upcase)'Notes
`with_entries()` is object-oriented `map()` over `to_entries` output.
Convert object to entries array
Represent an object as key-value entry objects.
bashANYjqentriesobjects
bash
echo '{"a":1,"b":2}' | jq 'to_entries'Notes
Useful when you need to filter or sort by object keys or values.
Convert entries back to object
Turn key-value entry objects into a normal object.
bashANYjqentriesobjects
bash
echo '[{"key":"a","value":1},{"key":"b","value":2}]' | jq 'from_entries'Notes
Often paired with `to_entries | map(...) | from_entries`.
Recursively transform all strings
Walk the document and mutate matching values.
bashANYjqwalkrecursive
bash
echo '{"name":"alice","nested":["dev","ops"]}' | jq 'walk(if type == "string" then ascii_upcase else . end)'Notes
`walk()` is very useful for recursive normalization when available in your jq version.
Strings and Formatting
Join, split, encode, decode, and shape text output.
bash
echo '["alice","bob","carol"]' | jq -r 'join(", ")'Notes
Great for turning arrays into CSV-like text.
bash
echo 'alice,bob,carol' | jq 'split(",")'Notes
jq can move fluidly between strings and arrays.
bash
echo '{"name":"alice","age":30}' | jq -r '"(.name) is (.age) years old"'Notes
Interpolation is one of jq's most useful shell-reporting features.
bash
echo '["alice",30,"SF"]' | jq -r '@csv'Notes
Use `@csv` for CSV-safe quoting and escaping.
bash
echo '["alice",30,"SF"]' | jq -r '@tsv'Notes
`@tsv` is useful for shell tables and spreadsheet imports.
bash
echo 'hello world@example.com' | jq -sRr @uriNotes
`-sRr` slurps raw text and returns an encoded plain string.
bash
echo 'hello world' | jq -sRr @base64Notes
Useful for quick payload generation in scripts.
bash
echo '"aGVsbG8gd29ybGQ="' | jq -r '@base64d'Notes
Input must be a JSON string containing base64 data.
Files, Slurp, and Streams
Read multiple inputs, raw lines, and streaming data.
bash
jq -s '.' file1.json file2.jsonNotes
`-s` slurps all input documents into one array before applying the filter.
bash
printf 'alpha
beta
' | jq -R '.'Notes
`-R` makes jq treat each line as a raw string.
bash
cat notes.txt | jq -Rs '.'Notes
`-Rs` is useful when you need to embed or encode an entire file.
Convert JSON lines into array
Turn multiple JSON documents into a single array.
bashANYjqndjsonslurp
bash
printf '{"id":1}
{"id":2}
' | jq -s '.'Notes
Great for NDJSON aggregation and batch transforms.
Use streaming parser
Process large JSON incrementally as path/value events.
bashANYjqstreamlarge-files
bash
jq --stream '.' large.jsonNotes
Streaming mode is advanced but valuable for huge documents.
bash
jq '{file: input_filename, value: .}' data.jsonNotes
Useful when processing many input files together.
More in jq
jq CLI Recipes
Real-world jq commands for APIs, cloud tooling, DevOps output, reporting, logs, and shell scripting.
jq Filters and Transformations
Advanced jq patterns for regex, booleans, dates, math, recursive descent, filtering, and output shaping.
jq Arrays and Objects
Deep reference for jq arrays, objects, grouping, entries, path updates, reshaping, and structural manipulation.