jq | JSON processor CLI cheatsheet

A JSON processor CLI that uses a domain-specific language (DSL).

What is jq? 🔗

A jq program is a “filter”: it takes an input, and produces an output. There are a lot of builtin filters for extracting a particular field of an object, or converting a number to a string, or various other standard tasks.

Filters can be combined in various ways - you can pipe the output of one filter into another filter, or collect the output of a filter into an array.

Some filters produce multiple results, for instance there’s one that produces all the elements of its input array. Piping that filter into a second runs the second filter for each element of the array. Generally, things that would be done with loops and iteration in other languages are just done by gluing filters together in jq.

It’s important to remember that every filter has an input and an output. Even literals like “hello” or 42 are filters - they take an input but always produce the same literal as output. Operations that combine two filters, like addition, generally feed the same input to both and combine the results. So, you can implement an averaging filter as add / length - feeding the input array both to the add filter and the length filter and then performing the division.

Common commands 🔗

Execute a specific expression only using the jq binary (print a colored and formatted JSON output):

jq '.' /path/to/file.json

Execute a specific script:

cat path/to/file.json | jq --from-file path/to/script.jq

Pass specific arguments:

cat path/to/file.json | jq --arg "name1" "value1" --arg "name2" "value2" ... '. + $ARGS.named'

Create new JSON object via old JSON objects from multiple files:

cat path/to/multiple_json_file_*.json | jq '{newKey1: .key1, newKey2: .key2.nestedKey, ... }'

Print specific array items:

cat path/to/file.json | jq '.[index1], .[index2], ...'

Print all array/object values:

cat path/to/file.json | jq '.[]'

Print objects with 2-condition filter in array:

cat path/to/file.json | jq '.[] | select((.key1=="value1") and .key2=="value2")'

Add or remove specific keys:

cat path/to/file.json | jq '. +|- {"key1": "value1", "key2": "value2", ... }'

For more details, check the official documentation on https://jqlang.org/manual/ .

I hope you enjoyed reading this post as much as I enjoyed writing it. If you know a person who can benefit from this information, send them a link of this post. If you want to get notified about new posts, follow me on YouTube , Twitter (x) , LinkedIn , and GitHub .