jq review: format and filter JSON from the command line

By ToolBrivio Editorial · Hands-on tests were run locally with jq 1.7 on Ubuntu 24.04.3. The current 1.8.2 release was checked in official documentation but not installed for this review. Source links earn no affiliate commission. Research approach · Disclosure.

You have a JSON response in a terminal and need the enabled audio track—not a full web editor. In our local test, one jq filter turned a compact recording manifest into a smaller object and returned exit code 0. The same executable rejected malformed JSON with exit code 5, which makes it useful in scripts as well as at the prompt.

What we actually tested

We ran jq 1.7 on x86-64 Ubuntu 24.04.3 on October 11, 2026. Input was passed through standard input, so no account, upload or network request was involved. These observations apply to that environment. The jq project currently offers 1.8.2 downloads for Linux, macOS and Windows; we did not retest the newer binary. Do not install jq 1.7 to reproduce these tests. Use the current official release or a security-supported distribution package, then recheck command behavior on that version.

{"episode":"launch","tracks":[{"name":"mic","enabled":true},{"name":"music","enabled":false}],"publishAt":1760169600}

First, jq '.' parsed and pretty-printed the object. Then this filter kept the episode name, selected enabled tracks and copied the timestamp:

jq '{episode, activeTracks: [.tracks[] | select(.enabled) | .name], publishAt}'

{
  "episode": "launch",
  "activeTracks": [
    "mic"
  ],
  "publishAt": 1760169600
}

The command exited 0. This is jq’s practical advantage over a formatter alone: a filter can validate, reshape and emit machine-readable output in one step.

Where jq was convenient

Files and pipes need no copy-and-paste step

jq accepts JSON from standard input or a filename. We also ran jq 'length' content/article-index.json against this site’s article index; it returned 29 with exit code 0. That makes jq a natural fit after a build command, API client or log export. A browser formatter is more approachable for one small snippet, but it introduces a manual paste step that does not belong in an automated check.

Exit status can carry meaning

With -e, jq returns status 0 when the last result is neither false nor null, status 1 for false or null, and status 4 when there was no valid result. We verified one branch:

printf '%s\n' '{"ready":false}' | jq -e '.ready'
# output: false
# exit status: 1

This is useful in a deployment check where “valid JSON” and “the flag is true” are different conditions. Without -e, a successful filter can exit 0 even when it prints false.

Streaming input is supported

Two newline-separated JSON objects passed through jq -c '.' emerged as two compact lines, both successfully parsed. The manual also documents --stream for incremental processing of large inputs. We did not benchmark memory use or large files, so this is a documented capability rather than a performance claim.

The limits that changed our recommendation

Duplicate keys are silently collapsed

We passed this object to jq '.':

{"role":"viewer","role":"admin"}

jq returned only {"role":"admin"} and exited 0. There was no duplicate-key warning. That behavior is risky when you are auditing configuration, access rules or a producer’s malformed export. ToolBrivio’s browser JSON formatter is the better first check for a small document when preserving number text and seeing duplicate-key warnings matters.

Arithmetic can lose large-integer precision

For {"id":9007199254740993}, the identity filter printed the original number in our build. But .id + 1 printed 9007199254740992, not the mathematical result. The jq 1.7 manual explains that arithmetic triggers conversion to IEEE 754 double precision. Treat long identifiers as strings, and do not use jq arithmetic for values that demand exact decimal or integer handling beyond the safe range.

Shell quoting is part of the learning curve

The filter language is compact, but the surrounding shell changes the quoting rules. The official manual gives different examples for Unix shells, PowerShell and Windows Command Prompt. A command copied from macOS may need different quoting in cmd.exe. If a filter grows beyond a short expression, storing it in a file with -f is easier to review than stacking escapes in a one-liner.

It is not a visual repair tool

jq points to a parse error—for our trailing comma sample it reported line 1, column 35 and exited 5—but it does not place a cursor beside the mistake or preserve an editable document. Someone repairing unfamiliar JSON may work faster in a browser or code editor. jq is strongest when the user already knows the field they need and wants a reproducible command.

jq versus ToolBrivio’s browser formatter

Neither option replaces a schema validator. Both can tell you whether text parses as JSON, but neither proves that a required field exists or that a timestamp has the meaning your application expects.

Who should use it

Choose jq if JSON arrives from command-line tools, build output or repeatable file-processing work. It is especially useful when the next step needs only a few fields or when success must be represented by an exit code. Installation is free: jq is MIT-licensed, and the official download page lists package-manager and standalone options for major desktop platforms.

Skip jq for a teammate who needs a visual interface, for duplicate-key investigations, or for exact large-number calculations. For occasional paste-and-format work, an in-browser formatter avoids installation and shell syntax. For application contracts, add a JSON Schema validator rather than stretching either formatter into a job it does not perform.

A safe first workflow

1. Install the current official release or a security-supported distribution package, then check jq --version; examples and number behavior can vary by release.
2. Start with jq '.' file.json to confirm that the input parses.
3. Write the smallest filter that returns the fields you need.
4. Add -e only when the filter result should control a script’s success.
5. Test malformed input, false/null, duplicate keys and large numeric identifiers before relying on the command in production.

Sources and next step

• jq 1.7 manual — filter model, options, exit status, quoting and numeric behavior.
• Official jq downloads — current binaries, platforms, signatures and license.
• jq 1.8.2 release — current release record; not the version used in our hands-on test.