jq is a small, fast command-line program for slicing, filtering, mapping, and transforming JSON. You pipe JSON into it and give it a filter that describes the shape you want out. It is a single self-contained binary with its own expressive language, and it is the standard tool for working with JSON in shell scripts and data pipelines.

What does .[] do in jq?

The .[] filter iterates over a collection and emits each value on its own. Given an array it streams every element, and given an object it streams every value while ignoring the keys. Because it produces many outputs, you usually pipe it into another filter, as in .users[] | .name to pull one field from each item in a list.

How do I filter an array with select?

Combine iteration with select. Write .[] | select(.age > 30) to stream each element and keep only the ones where the test is true; select passes its input through when the condition holds and produces nothing otherwise. Wrap the whole thing in square brackets, like [.[] | select(.age > 30)], when you want the survivors collected back into an array.

How do I output raw strings instead of quoted JSON?

Add the -r (or --raw-output) flag. By default jq prints string results as JSON, wrapped in double quotes and with escapes; -r writes the bare text instead, which is what you want when feeding the output into other shell commands. There is also -j (--join-output), which is like -r but does not add a newline between results.

What does the pipe do in jq?

The pipe passes the output of the filter on its left as the input to the filter on its right, much like a Unix shell pipe but operating on JSON values. Because a filter can emit several values, the right-hand side runs once for each value that arrives. Chaining short filters with the pipe is the normal way to build up a larger transformation step by step.

Does this cheat sheet send my JSON or searches anywhere?

No. Every filter and description is baked into the page, and all searching and category filtering happens locally in your browser with JavaScript. Nothing you type is uploaded, and the tool needs no server to work. Open your browser DevTools and watch the Network tab while you search to confirm there are zero requests.

jq JSON Cheat Sheet

A searchable reference of common jq filters and operators and what each one does.

Filter

Common jq filters with a plain-English description of what each one does
Filter	What it does
`jq .`	Pretty-print the whole input by echoing it through the identity filter.
`jq .field`	Extract the value of a named top-level field from an object.
`jq .a.b`	Reach into a nested value by chaining keys with dots.
`jq .[0]`	Get the item at index 0 of an array; a negative index counts from the end.
`jq .[]`	Iterate over a collection, emitting every array element or object value on its own.
`jq .array[]`	Stream each element of the array held in the field named array.
`jq -r .name`	Output raw strings without JSON quotes or escapes, one result per line.
`jq -c .`	Print each result on one compact line instead of pretty-printed JSON.
`jq .name?`	Return the field if present and stay quiet instead of erroring when the input is not an object.
`select(.age > 30)`	Pass the input through only when the condition is true, dropping everything else.
`has("id")`	Test whether an object has the given key, or an array has the given index.
`keys`	List the keys of an object (sorted) or the indices of an array.
`values`	Keep only inputs that are not null; use .[] to stream the values of an object.
`length`	Return the length: element count for arrays, key count for objects, character count for strings.
`type`	Return the type of the input as a string such as "number", "string", or "object".
`contains("lo")`	Test whether the input contains the given value: substring for strings, structural for arrays and objects.
`in(["a","b"])`	Check whether the input key or index exists in the given container (the inverse of has).
`empty`	Produce no output at all, which removes a result from the stream.
`.items \| length`	Feed the output of the left filter into the right filter using the pipe.
`map(.price)`	Apply a filter to every element of an array and collect the results into a new array.
`add`	Combine all elements of an array by summing numbers or concatenating strings and arrays.
`sort_by(.age)`	Sort an array by the value the given filter returns for each element.
`group_by(.dept)`	Group array elements that share a key value into sub-arrays; sort the input first.
`unique`	Sort an array and remove duplicate values.
`reverse`	Reverse the order of an array or the characters of a string.
`min, max`	Return the smallest and the largest element of an array.
`flatten`	Flatten nested arrays into one flat array; pass a depth to limit how far it goes.
`del(.password)`	Delete a key or array element and return the rest of the structure.
`{name: .user, age: .yrs}`	Build a new object with the keys and values you choose.
`[.user, .id]`	Gather one or more results into a new array using square brackets.
`"\(.name) is here"`	Embed a value inside a string using backslash-parenthesis interpolation.
`join(",")`	Join an array of values into a single string separated by the given text.
`split(",")`	Split a string into an array on the given separator.
`ascii_downcase`	Convert the ASCII letters of a string to lowercase; ascii_upcase does the reverse.
`tostring`	Convert the input to its string form, leaving existing strings unchanged.
`tonumber`	Parse a string into a number, leaving existing numbers unchanged.
`..`	Walk recursively through every value at every depth; .. is shorthand for recurse.
`.name // "anon"`	Use the left side, or fall back to the right side when the left is null, false, or empty.
`if .n > 0 then "pos" else "neg" end`	Branch on a condition; elif and else are optional but end is required.
`reduce .[] as $x (0; . + $x)`	Fold a running result over every item in a stream to accumulate one value.
`--arg name value`	Bind a command-line string to the variable $name inside the filter.
`jq -s .`	Read the entire input stream into one array before filtering (slurp mode).
`to_entries`	Turn an object into an array of key and value pair records.
`from_entries`	Rebuild an object from an array of key and value pair records (the inverse of to_entries).
`paths`	List the path to every element in the input as an array of keys and indices.

Runs entirely in your browser. Nothing you type is sent anywhere; open DevTools and watch the Network tab to verify zero requests.

What this tool does

This is a searchable quick reference for jq, the command-line JSON processor. Each row pairs a jq filter, flag, or operator with a plain-English note on what it does, grouped from the basics of reaching into fields through selecting, transforming, and building JSON. Type in the filter box to search across both columns, or tap a category button to focus on one area. The whole list is built into the page, so it works offline and sends nothing anywhere.

How to use it

Start typing in the Filter box. Entering select jumps to the test-and-keep filters; entering -r surfaces raw output; entering map or sort shows the array transforms. The category buttons (Basics, Select and test, Transform, Construct, Advanced) narrow the table to one family and combine with the text filter, so you can pick Transform and type group to zero in on group_by. Clear the box to see the full sheet again.

Common use cases

Recalling the exact syntax for a filter you use rarely, like reduce or to_entries.
Copying a working filter into your terminal instead of guessing at the jq language.
Pulling one field out of every record in a JSON array with .[] and a pipe.
Reshaping an API response into a flat, readable form before piping it onward.
Learning the difference between select, map, and has.

Common pitfalls

Forgetting -r for raw output. Without -r, jq prints strings wrapped in JSON quotes with escapes, which breaks scripts that expect bare text. Add -r when the result is a plain string you want to use directly.
Shell quoting. A jq program lives inside your shell, so wrap the whole filter in single quotes to stop the shell from expanding $, spaces, and glob characters before jq ever sees them.
Confusing select with map. select keeps or drops whole inputs based on a test, while map transforms every element of an array. Reach for select to filter and map to change values.
Mixing up -c and -r. -c makes the output compact on one line but keeps it valid JSON with quotes, while -r strips the quotes from strings. They solve different problems and are often used together.

Frequently asked questions

What is jq?: jq is a small, fast command-line program for slicing, filtering, mapping, and transforming JSON. You pipe JSON into it and give it a filter that describes the shape you want out. It is a single self-contained binary with its own expressive language, and it is the standard tool for working with JSON in shell scripts and data pipelines.
What does .[] do in jq?: The .[] filter iterates over a collection and emits each value on its own. Given an array it streams every element, and given an object it streams every value while ignoring the keys. Because it produces many outputs, you usually pipe it into another filter, as in .users[] | .name to pull one field from each item in a list.
How do I filter an array with select?: Combine iteration with select. Write .[] | select(.age > 30) to stream each element and keep only the ones where the test is true; select passes its input through when the condition holds and produces nothing otherwise. Wrap the whole thing in square brackets, like [.[] | select(.age > 30)], when you want the survivors collected back into an array.
How do I output raw strings instead of quoted JSON?: Add the -r (or --raw-output) flag. By default jq prints string results as JSON, wrapped in double quotes and with escapes; -r writes the bare text instead, which is what you want when feeding the output into other shell commands. There is also -j (--join-output), which is like -r but does not add a newline between results.
What does the pipe do in jq?: The pipe passes the output of the filter on its left as the input to the filter on its right, much like a Unix shell pipe but operating on JSON values. Because a filter can emit several values, the right-hand side runs once for each value that arrives. Chaining short filters with the pipe is the normal way to build up a larger transformation step by step.
Does this cheat sheet send my JSON or searches anywhere?: No. Every filter and description is baked into the page, and all searching and category filtering happens locally in your browser with JavaScript. Nothing you type is uploaded, and the tool needs no server to work. Open your browser DevTools and watch the Network tab while you search to confirm there are zero requests.

Embed this tool

Free for any use; attribution appreciated. Paste this on your site:

<iframe
  src="https://glunty.com/jq-cheatsheet?embed=1"
  width="100%"
  height="600"
  style="border:1px solid #e5e5e5;border-radius:6px;max-width:100%;"
  title="jq JSON Cheat Sheet (via glunty.com)"
  loading="lazy"
  referrerpolicy="strict-origin-when-cross-origin"
></iframe>

The embed runs the same tool that lives at this URL. No tracking; no ads inside the embed. Resize height as needed for your layout.

Cite this tool

For academic, journalistic, or technical references. Pick a format:

https://glunty.com/jq-cheatsheet

Citations use 2026 as the publication year. Access date is left as a fillable placeholder where the citation style expects one.

Embedded tool from glunty.com