jq Cheatsheet

Basic Info

• jq: for JSON
  • written in portable C; 0 external dependencies.
  • Source: https://github.com/stedolan/jq

Select

$ jq '.name' file.json

# used with pipes
$ cat file.json | jq '.a.b[0].c'

# pretty print
$ cat file.json | jq

Multiple fields:

# from top level
$ cat file.json | jq '. | {field1, field2}'

# from sub level
$ cat file.json | jq '.results[] | {id, name}'

Extract as text values instead of JSON (getting rid of quotes), use -r:

$ cat file.json | jq -r '.a.b[0].c'

Slice an array

$ echo '["a", "b", "c", "d"]' | jq '.[1:3]'

Filter

# get "name" of id 1
$ cat file.json | jq '.results[] | select(.id == "1") | {name}'

# get result with multiple filters
$ cat file.json | jq '.results[] | select((.id == "1") and (.name="a"))'

# filter with substrings
$ cat file.json | jq '.results[] | select(.name | contains("ab"))'

# filter with regex
$ cat file.json | jq '.results[] | select(.name | test("Joe\s+Smith"))'

Replace

Given a list (items[]), find the item according to .spec.foo, change the value of .spec.bar to baz:

cat file.json | jq '(.items[] | select(.spec.foo == "key")).spec.bar |= "baz"'

Functions

Selectors start with .. Functions do not.

$ echo '{ "a": 1, "b": 2 }' | jq 'keys' # [a, b]

• keys: get keys of the objects.
• length: get the length of the array or the number of the keys. (e.g. select non-empty arrays select(.my_array | length > 0))
• flatten: flatten nested arrays.
• unique: get the unique values of an array.
• join: join the elements using a separator (e.g. cat file.json | jq '[.a, .b] | join(" ")'))

Create new objects

$ echo '{ "a": 1, "b": 2 }' | jq '{ a: .b, b: .a }'
# { "a": 2, "b": 1 }

Delete Values

$ jq 'del(.somekey)' input.json

Extract Raw

Use -r to extract raw text values instead of JSON:

$ jq -r '.tags | .[] | select(contains("1.0.0")) | length'

Example: Harbor

# Get repositories (in a JSON array)
$ curl -u $USERNAME:$PASSWORD https://$IP:$PORT/v2/_catalog | jq -r '.repositories'

# Get repositories (in a raw list)
$ curl -u $USERNAME:$PASSWORD https://$IP:$PORT/v2/_catalog | jq -r '.repositories | .[]'

# Get number of repositories
$ curl -u $USERNAME:$PASSWORD https://$IP:$PORT/v2/_catalog | jq -r '.repositories | length'

How to pass shell env param to jq?

$ cat manifest.json | jq --arg CLUSTER_UID $CLUSTER_UID '.metadata.ownerReferences[0].uid = $CLUSTER_UID' > modified.json

How to decode base64?

... | jq -r '.data.password | @base64d'

How to remove prefix and substitute?

# jq remove prefix and substitute, e.g. https://10.200.0.19:10443=>10.200.0.19.10443
... | jq -r 'ltrimstr("https://") | sub(":";".")'

How to deal with field name with .?

# field name with `.`
... | jq -r '.data."ca.crt"'

Install jq

# macOS
brew install jq

# Debian / Ubuntu
sudo apt install jq

Other platforms: https://jqlang.github.io/jq/download/