hereink

How to use jq: install, filter JSON keys, map arrays, pipe with curl

Install jq, pull JSON fields, map arrays, and shrink API responses with curl pipes.

When you debug REST APIs or CI logs, jq lets you filter and reshape JSON in the terminal instead of pasting megabytes into an editor. This guide covers official installs on macOS, Linux, and Windows, field filters, array mapping, and curl pipes for hereink readers who live in the shell.

The query is how to use jq with JSON and pipe curl output. You should finish able to install jq, read .key paths, map arrays, and shrink an API body to a few readable lines.

Installbrew / apt / winget
Filter.field · .[] · select
Pipecurl -s … | jq

What jq fixes

More than python -m json.tool

Python’s json.tool only pretty-prints. jq can print .data.items[0].id, filter arrays, or flatten nested objects—handy for scripts and one-off debugging.

Natural curl partner

API bodies are often hundreds of lines. Append | jq '.field' and the terminal shows only the keys you need.

Check the build: jq --version. Manual and downloads: jqlang.org, GitHub org jqlang/jq.

Install jq on three OSes

  1. 1
    macOS (Homebrew)

    Run brew install jq. Verify with which jq and jq --version. Same formula on Apple Silicon and Intel.

  2. 2
    Linux (distro packages)

    Debian/Ubuntu: sudo apt update && sudo apt install jq. Fedora: sudo dnf install jq. Arch: sudo pacman -S jq. If the repo lags, grab a static binary from GitHub Releases.

  3. 3
    Windows

    PowerShell: winget install jqlang.jq, or Chocolatey: choco install jq. Open a new terminal and run jq --version.

  4. 4
    First filter

    Test: echo '{"ok":true,"n":3}' | jq .ok should print true. Pretty whole object: echo '{"a":1}' | jq ..

Filter keys and map arrays

# Extract nested field
echo '{"user":{"name":"Lin","role":"admin"}}' | jq .user.name

# Expand array elements
echo '{"items":[{"id":1},{"id":2}]}' | jq '.items[]'

# Map: keep ids only
echo '{"items":[{"id":1,"x":0},{"id":2,"x":1}]}' | jq '.items | map(.id)'

# Conditional filter
echo '[{"k":"a","v":1},{"k":"b","v":2}]' | jq '[.[] | select(.v > 1)]'

# Pick multiple keys
echo '{"a":1,"b":2,"c":3}' | jq '{a,b}'

Wrap filters in single quotes so the shell does not expand $. Dot . means the current JSON value; [] iterates arrays.

Pipe with curl

ScenarioExampleNote
Public API metadatacurl -s https://api.github.com/repos/jqlang/jq | jq '{name, description, stars: .stargazers_count}'Only name, description, stars
Raw token for scriptscurl -s … | jq -r '.token'-r strips JSON string quotes
Compact log linescurl -s … | jq -c '.items[]'One object per line; pipe to rg
Private APIcurl -s -H "Authorization: Bearer $TOKEN" … | jq .jq processes the body only
Fits
Inspecting REST fields, filtering JSON log lines from containers, parsing CI build metadata.
Does not fit
Large in-place JSON edits (use redirects or config tools); non-JSON text (use grep/rg first).
What does jq: parse error mean?

Input is not valid JSON (trailing commas, single-quoted strings, or headers mixed into the pipe). Test with jq . alone; for NDJSON try jq -s or line-by-line processing.

Windows says jq is not recognised?

Restart the terminal after install. Run where jq. winget and Chocolatey usually add PATH automatically.

Is jq the same as yq?

No. jq is for JSON. YAML needs yq or a conversion step. jq is the usual choice for API debugging.

After fields, draw the boundary

Once the terminal shows the API shape, service boundaries still belong on one shared board. See how to create a space.

Start a room