jq: command-line JSON processor
jq [-r] [-c] [-n] [-s] [-e] [--arg NAME VALUE] 'FILTER' [file]
Options you will use
-r, --raw-output- Strings come out without quotes - required before you pipe into anything else.
-c, --compact-output- One line per result.
-s, --slurp- Read the whole input into one array.
-n, --null-input- Do not read input; useful with --arg.
-e, --exit-status- Exit 1 if the last output was false or null. For if-tests.
--arg NAME VALUE- Pass a shell value in as $NAME, safely.
.a.b / .[] / .[]?- Field access, array iteration, tolerant iteration.
select(COND) / map(F)- Filter, and apply to every element.
@tsv @csv @json- Format an array as TSV, CSV or a JSON string.
trim / ltrimstr(S) / rtrimstr(S)- Strip surrounding whitespace, or a prefix / suffix. trim, ltrim, rtrim and trimstr are new in jq 1.8; since 1.8 ltrimstr/rtrimstr error on a non-string instead of passing it through.
--version- Print the version: jq-1.8.1 on Ubuntu 26.04.
--argjson NAME JSON- Set $NAME to a JSON value (a number, true, an object) - unlike --arg, which always makes a string.
Examples
$ jq '.items | length' pods.jsonhow many
$ jq -r '.items[] | select(.status.phase != "Running") | .metadata.name' pods.jsonthe unhappy pods
$ jq -r '.items[] | [.metadata.namespace, .metadata.name] | @tsv' pods.jsontwo fields as TSV
$ jq -r '.. | .image? // empty' pods.json | sort -uevery image anywhere in the document
Taught in
- 0.2 Percentiles by hand, and why they do not average
- 0.9 Choosing what to count: valid events, measurement points, windows
- 7.11 jq
- 7.13 jq beyond select
- 12.53 Image anatomy: manifest, config, layers, digests
- 24.21 PKI and transit: certificates on demand, encryption as a service
- 24.30 Operating Vault: health, audit devices, snapshots, the seal, upgrades, OpenBao
- 24.34 Terraform and Vault: the vault provider, and secrets in state
On the blog
Try jq in a real terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.