Jq Cheatsheet

THE PRACTICAL GUIDE · NORMANDIN SYSTEMS

Get more from Jq Cheatsheet

Jq Cheatsheet summarizes common jq filters for selecting and transforming JSON from a command line. jq works with structured JSON values rather than plain text lines, which makes it useful for nested objects and arrays. Shell quoting is a separate concern: the shell must pass the intended filter to jq without expanding or consuming its special characters. A cheatsheet works best as a memory aid while you practice a concrete task. Read the command or syntax together with its arguments, placeholders, and surrounding context. Similar-looking options can have very different meanings, and an example written for one platform or version may need adjustment elsewhere. Keep the reference beside a small test case, use read-only examples first when possible, and check the relevant help output before applying an unfamiliar command to valuable files or a running service.

Guide updated October 13, 2026

How to use this tool

1. Identify the operation you want to perform and find the matching section of the reference. Read the whole example before copying any part of it.
2. Find a filter matching the required selection or transformation, then try it against a small known JSON document.
3. Review the example below and compare its expected behavior with a small sample of your own input before continuing.
4. Try the adapted example on a small test case, compare the result with the explanation, and save the command with a note about the context in which it works.

SEE IT IN PRACTICE

A worked example

JSON {"name":"Ada"} with jq filter .name

The JSON string "Ada", or Ada with an appropriate raw-output option

The filter selects the name property; output representation depends on jq's chosen flags.

JSON values are not plain lines

jq understands objects, arrays, strings, numbers, booleans, and null. Selecting an array element or mapping over a collection therefore differs from cutting a line of text at a delimiter. Start with a small known document and inspect the type and number of outputs at each stage. A filter can produce a stream of values rather than one JSON array, which matters when another command expects a single document. Choose output flags deliberately, especially when raw strings are needed.

Shell quoting is a separate layer

The shell must pass the intended jq program without consuming quotes, dollar signs, or wildcard characters. Examples copied between shells can require different quoting even when the jq filter is unchanged. Distinguish a missing property, a null value, an empty array, and no output at all when handling failures. Test the exact command in the destination shell with representative data before embedding it in automation. Preserving a small fixture makes future filter changes easier to verify.

When this tool is useful

• Extract a field from an API fixture
• Review a nested JSON transformation
• Prepare a repeatable command-line data inspection

Tips for a better result

• Check the number and types of results, and verify shell quoting in the actual environment where the command will run.
• Replace example paths, identifiers, and names deliberately. Copying a reference command unchanged can target a different file, branch, service, or environment from the one you intended.
• Keep the source and the settings used for this result together. That makes a later comparison or correction easier, especially when another person needs to reproduce the same outcome.

Frequently asked questions