json · wleeaf field noteshttps://articles.wleeaf.dev/tags/json/Hands-on guides and build logs from the wleeaf studio: self-hosting, Linux, networking, Docker, the command line and reverse engineering.en-usFri, 27 Mar 2026 00:00:00 +0000jq Is the SQL of JSONhttps://articles.wleeaf.dev/posts/jq-command-line-json/Fri, 27 Mar 2026 00:00:00 +0000https://articles.wleeaf.dev/posts/jq-command-line-json/Every API returns JSON now. jq turns your terminal into a query engine for it.clijsonlinuxEvery API you talk to returns JSON. Every config file is JSON. Every log pipeline emits JSON. And yet most people still pipe curl output through grep and pray.

jq is the tool that makes JSON usable from the command line. Once you learn the basics, you will never go back.

Basics#

Pretty-print some JSON:

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

Extract a single field:

bash
echo '{"name": "Linus", "repos": 5}' | jq .name
# "Linus"

Drop the quotes with -r:

bash
echo '{"name": "Linus"}' | jq -r .name
# Linus

Arrays#

Get the first element:

bash
echo '[1, 2, 3]' | jq '.[0]'
# 1

Iterate over all elements:

bash
echo '[{"name": "a"}, {"name": "b"}]' | jq '.[].name'
# "a"
# "b"

Filtering#

This is where it gets powerful. Say you have a list of GitHub repos:

bash
curl -s https://api.github.com/users/torvalds/repos | \
  jq '[.[] | select(.stargazers_count > 1000)] | length'

That filters repos with more than 1000 stars and counts them.

Constructing Objects#

You can reshape JSON on the fly:

bash
curl -s https://api.github.com/users/torvalds/repos | \
  jq '.[] | {name: .name, stars: .stargazers_count, lang: .language}'

This outputs a new object for each repo with only the fields you care about.

Real World: Parsing Docker#

List container names and their memory usage:

bash
docker stats --no-stream --format '{{json .}}' | \
  jq -r '[.Name, .MemUsage] | @tsv'

Find containers using more than 100MB:

bash
docker stats --no-stream --format '{{json .}}' | \
  jq -r 'select(.MemPerc | gsub("%"; "") | tonumber > 1) | .Name'

Working With Nested Data#

Given deeply nested JSON:

json
{
  "data": {
    "users": [
      {"id": 1, "profile": {"email": "a@b.com"}},
      {"id": 2, "profile": {"email": "c@d.com"}}
    ]
  }
}

Extract all emails:

bash
jq '[.data.users[].profile.email]' data.json
# ["a@b.com", "c@d.com"]

Combining With Other Tools#

jq plays well with the rest of the Unix toolkit:

bash
# Get all unique languages across repos
curl -s https://api.github.com/users/torvalds/repos | \
  jq -r '.[].language // empty' | sort -u

# Convert JSON array to lines for xargs
echo '["file1.txt", "file2.txt"]' | jq -r '.[]' | xargs rm

# Merge multiple JSON files
jq -s 'add' file1.json file2.json > merged.json

The Cheat Sheet#

Pattern What it does
.field Get field
.[] Iterate array
select(cond) Filter
map(expr) Transform array
length Count
keys Object keys
to_entries Object to key-value pairs
@csv Output as CSV
@tsv Output as TSV
// Default value

jq has a learning curve, but it is one of those tools where the investment pays off within a week. Every time you find yourself writing a Python script just to parse some JSON, remember that jq probably does it in one line.

]]>