JSON

Getting Started

jq is the standard command-line JSON processor: it reads JSON from a file or stdin, applies a filter, and prints the result. The simplest filter, ., just pretty-prints.

$ jq "." file.json

$ curl -s https://api.github.com/users/torvalds | jq "."

$ echo '{"name": "Linux"}' | jq "."

Alternatives with their own strengths: jaq (faster jq clone), dasel (also speaks YAML, TOML, XML), fx and jless (interactive viewers), gron (makes JSON greppable), jo (creates JSON), jc (converts classic command output to JSON).

Selecting Values

Filters address values by path: .key for object fields, [0] for array indexes, [] to iterate over all elements. -r prints strings raw, without quotes.

$ echo '{"name": "Linux"}' | jq ".name"

$ jq ".user.address.city" file.json

$ jq ".items[0]" file.json

$ jq -r ".items[].name" file.json

The same selection in other tools:

$ echo '{"name": "Linux"}' | dasel -r json '.name'

$ echo '{"name": "Linux"}' | fx .name

$ echo '{"name": "Linux"}' | jshon -e name

Filtering & Transforming

jq filters chain with | just like shell pipes. select() keeps matching elements, map() transforms each one.

$ jq '.items[] | select(.price > 10)' file.json

$ jq '.items | map(.name)' file.json

$ jq '.items | length' file.json

$ jq 'keys' file.json

$ jq '.items | sort_by(.price)' file.json

Build new objects from existing fields.

$ jq '.items[] | {title: .name, cost: .price}' file.json

Modifying

Set or add a field with =, remove one with del(). jq never edits in place; redirect the output to a new file.

$ echo '{"name": "Linux"}' | jq '.year = 1991'

$ echo '{"name": "Linux", "year": 1991}' | jq 'del(.year)'

$ echo '{"name": "Linux"}' | dasel put string -r json '.year' '1991'

$ echo '{"name": "Linux", "year": 1991}' | dasel delete -r json '.year'

Creating

jo builds JSON from shell arguments; jq -n builds it from a filter alone.

$ jo -p name=Linux year=1991

$ jq -n '{name: "Linux", year: 1991}'

Grepping & Exploring

gron flattens JSON into discrete assignments so you can use plain grep, then reassembles it with -u. jless and fx browse large documents interactively with folding and search.

$ gron file.json | grep "name"

$ gron file.json | grep "name" | gron -u

$ jless file.json

$ fx file.json

Converting

yq applies jq-style filters to YAML, and dasel converts between formats. jc turns the output of classic commands into JSON so you can process it with jq.

$ yq ".name" config.yaml

$ dasel -r json -w yaml < file.json

$ jc ifconfig | jq ".[0].ipv4_addr"

Compact output for machines: jq -c prints one line per document, useful for JSON Lines streams.