jq and structured text — JSON, YAML, and CSV at the command line · Linux

Modern infrastructure tooling speaks JSON: cloud APIs, container runtimes, monitoring agents, configuration management, and most service-discovery systems. jq is the universal JSON processor on Linux and is the right tool for almost every JSON triage task.

The basic jq filter

A jq filter describes what to extract from a JSON value:

echo '{"name":"web01","status":"running"}' | jq '.name'
# "web01"

The leading . is the identity filter; .name selects the name field. By default jq pretty-prints its output.

Read-only / Safejq field access— The dot-name filter extracts a single field. The output is the JSON string 'web01' (with quotes preserved). jq distinguishes between strings (with quotes) and other types.

$ echo "{\"name\":\"web01\",\"status\":\"running\"}" | jq ".name"

"web01"

Illustrative output

Read-only / Safejq raw output— -r (raw output) strips JSON string quoting. Use -r when feeding jq output into another shell command or a file.

$ echo '{"name":"web01","status":"running"}' | jq -r '.name'

web01

Illustrative output

Arrays and iteration

A JSON array is iterated with [] or , (the comma form generates multiple output records):

Read-only / Safeiterate array— .[].name iterates the array and extracts 'name' from each element. This is the canonical 'iterate all entries' pattern.

$ echo '[{"name":"web01"},{"name":"db01"},{"name":"cache01"}]' | jq -r '.[].name'

web01
db01
cache01

Illustrative output

Read-only / Safejq filter and project— select() filters records. The pipe | chains filters. This is the jq equivalent of a SQL SELECT … WHERE.

$ echo '[{"name":"web01","status":"running"},{"name":"db01","status":"stopped"}]' | jq -r '.[] | select(.status == "running") | .name'

web01

Illustrative output

Nested objects

For nested objects, use . chaining or […] for bracketed paths:

Read-only / Safenested access— Chained dots walk the tree. Bracket syntax .host.network["ip"] is equivalent but useful when the field name contains special characters.

$ echo '{"host":{"network":{"ip":"10.0.0.5"}}}' | jq -r '.host.network.ip'

10.0.0.5

Illustrative output

Read-only / Safenested arrays— Combine .items[] to iterate, then .name to extract.

$ echo '{"items":[{"name":"a"},{"name":"b"}]}' | jq -r '.items[] | .name'

a
b

Illustrative output

Constructing output

jq can build new JSON objects from the input:

Read-only / Safejq string interpolation— \\(...) interpolates a value into a string. Useful for human-readable output.

$ echo '[{"name":"web01","port":8080},{"name":"db01","port":5432}]' | jq -r '.[] | "(.name):(.port)"'

web01:8080
db01:5432

Illustrative output

Read-only / Safejq reshape— jq builds a new array of objects with renamed keys. The original keys are not preserved unless you include them.

$ echo '[{"name":"web01","port":8080}]' | jq '[.[] | {host: .name, port: .port}]'

[
{
"host": "web01",
"port": 8080
}
]

Illustrative output

Handling missing keys gracefully

A common jq mistake is getting the literal text null for keys that do not exist in every record. The fix is the alternative operator. In jq that means two slash characters in a row

This file had MDX parser issues that the build process is recovering from.

Read-only / Safejq default value— The alternative operator provides a fallback when the left-hand side is null or false. Useful for records where a field may be missing.

$ echo '[{"name":"web01"},{"name":"db01","port":5432}]' | jq -r '.[] | "(.name):(.port // "unknown")"'

web01:unknown
db01:5432

Illustrative output

YAML and CSV

YAML and CSV are common in infrastructure but lack jq’s universal filters:

Read-only / Safeyq— yq (mikefarah/yq) uses jq-like syntax for YAML. The .spec.containers[].image filter extracts image references from a Kubernetes manifest.

$ yq -r '.spec.containers[].image' deployment.yaml

nginx:1.27
prom/node-exporter:1.8

Illustrative output

Read-only / Safepython for CSV— CSV is irregular enough that python's csv module is usually the right tool. mlr (Miller) is a jq-like alternative for CSV/TSV/JSON.

$ python3 -c 'import csv,sys; r=csv.DictReader(sys.stdin); print("\n".join(row["name"] for row in r))' < users.csv

alice
bob
carol

Illustrative output

The basic jq filter

Arrays and iteration

Nested objects

Constructing output

Handling missing keys gracefully

YAML and CSV

Knowledge check