jq Tutorial: Query and Transform JSON on the Command Line

The mental model: filters and streams

jq is built around filters that run over a stream of JSON. Each filter takes JSON input and emits JSON output, and you connect filters with the pipe operator just like in a Unix shell. Master that one idea — input flows through a chain of small filters — and the rest of jq is just learning which filters exist.

The identity filter and pretty-printing

The simplest filter is . (a single period), the identity filter: it passes input through unchanged. Running curl ... | jq '.' formats and colorizes a JSON response, which alone makes jq worth installing. From there, . is also the starting point for navigation: .name reads the name field, and .user.email walks into nested objects.

echo '{"name":"Ada","age":36}' | jq '.'

Accessing fields and arrays

• .name — read a top-level field
• .user.email — read a nested field
• .items[0] — the first array element
• .items[] — stream every element of an array, one at a time
• .items[].name — the name of every element

Filtering with select

select takes a boolean condition and passes through only the inputs that match — it is the WHERE clause of jq. Combined with the array-streaming syntax, .items[] | select(.price < 10) emits only the items cheaper than ten. You can compose conditions with and, or, and not, and compare strings and numbers, making select the workhorse for extracting the records you care about.

echo '{"items":[{"price":5},{"price":20}]}' \
  | jq '.items[] | select(.price < 10)'
# → {"price":5}

Transforming with map and building objects

map applies a filter to every element of an array and rewraps the results, so map(.price) turns an array of objects into an array of prices. To reshape data, build a new object with curly braces: .items[] | {name: .name, cost: .price} emits a slimmed-down object for each item. The add filter sums an array of numbers, and length returns sizes — combine these to compute totals and summaries in one line.

jq 'map(.price)'                      # [5, 20]
jq '.items[] | {name, cost: .price}'  # build new objects

Compact output and raw strings

Two flags come up constantly. The -c flag emits compact, one-line output — and since that is one JSON value per line, it is how you produce JSONL from jq. The -r flag outputs raw strings without quotes, which you want when piping a value into another shell command. Together, jq -r '.items[].name' prints each name on its own line, ready for a loop.

jq versus browser tools

jq shines for scripting and pipelines, but for a quick interactive look at a payload, a browser tool is faster. A JSON Path extractor runs queries against pasted JSON without the shell, a tree viewer lets you explore structure visually, and a formatter pretty-prints without installing anything. Use jq in your terminal workflows and the visual tools when you just need to read or probe a document.