jq for JSON Processing from the Terminal

APIs, config files, and CLI tools all speak JSON. Once the payload is on your machine, you often need a slice of it: one field, a filtered list, or a flatter shape for a spreadsheet. jq is the standard tool for that job in the terminal — fast, scriptable, and available on almost every developer machine.

This guide covers the filters you will reach for daily, how to pipe jq into the rest of your shell workflow, and when a private browser tool is a better fit than writing a one-liner.

What jq is

jq is a lightweight command-line JSON processor. You pass it JSON on stdin (or a file), give it a filter expression, and it prints the result. Filters can select fields, walk arrays, rewrite objects, and format output — all without writing a Python or Node script.

Think of it as sed / awk for structured data: small expressions, big leverage in pipelines.

Install

On macOS with Homebrew:

brew install jq

On Debian/Ubuntu:

sudo apt install jq

Confirm with jq --version. Windows users can install via winget, Chocolatey, or download a binary from the official jq releases.

Identity and pretty-print

The simplest useful filter is . — the identity. It pretty- prints JSON, which is already enough for many API responses:

curl -s https://api.example.com/user | jq .
cat data.json | jq .
jq . data.json

Compact (one-line) output uses -c:

jq -c . data.json

For a quick format-only pass in the browser — no install required — use JSON Formatter.

Select fields

Dot paths pull nested values:

jq '.name' user.json
jq '.address.city' user.json
jq '.user.profile.email' response.json

Build a smaller object with the object constructor. Keys on the left are output names; values on the right are paths into the input:

jq '{name: .name, city: .address.city}' user.json

Missing paths become null. Use the optional operator ? when a key might not exist:

jq '.address?.city' user.json

Work with arrays

.[] streams each element. Combine with a path to project a field from every item:

jq '.[].id' users.json
jq '.items[].sku' order.json
jq '.[] | {id, name}' users.json

Index and slice like most languages:

jq '.[0]' users.json
jq '.[-1]' users.json
jq '.[0:3]' users.json

length, keys, and type are handy for inspection:

jq 'length' users.json
jq 'keys' user.json
jq 'map(type)' mixed.json

Filter rows

select keeps values that match a condition. Pipe array elements into it:

jq '.[] | select(.active == true)' users.json
jq '.[] | select(.price > 100)' products.json
jq '.[] | select(.role == "admin")' users.json
jq '[.[] | select(.status == "open")]' tickets.json

The last form wraps results back into an array (useful when the next step expects a JSON array, not a stream of objects).

String matching uses contains, startswith, or test (regex):

jq '.[] | select(.email | endswith("@example.com"))' users.json
jq '.[] | select(.name | test("(?i)acme"))' orgs.json

Map and reshape

map transforms every element of an array:

jq 'map({id, name})' users.json
jq 'map(.price * 1.1)' products.json
jq 'map(.tags[])' posts.json

Nested objects often need flattening before CSV or Excel. In jq you can pull nested paths into top-level keys:

jq 'map({
  id,
  name,
  city: .address.city,
  zip: .address.zip
})' users.json

Prefer a visual flatten when you are exploring unfamiliar payloads: Flatten JSON, then export with JSON to CSV. For the full flatten story, see Flatten Nested JSON for Spreadsheets and CSV.

Export CSV from the terminal

jq can emit CSV with @csv. Headers are manual — build a header row, then map data rows:

jq -r '
  (["id","name","city"]),
  (.[] | [.id, .name, .address.city])
  | @csv
' users.json

-r (raw output) drops JSON string quotes so the result is plain CSV. For one-off exports without shell scripting, JSON to CSV or JSON to Excel may be faster.

Useful flags

• -r — raw strings (no quotes); needed for CSV and plain text.
• -c — compact, one object per line.
• -s — slurp: read the whole input stream into one array.
• -n — null input; build JSON from the filter alone.
• --arg name value — pass a shell string into the filter as $name.

jq --arg city "Berlin" \
  '[.[] | select(.address.city == $city)]' users.json

Recipes worth memorizing

# Sort objects by a field
jq 'sort_by(.created_at)' events.json

# Unique values of a field
jq '[.[].status] | unique' tickets.json

# Group by key
jq 'group_by(.role) | map({role: .[0].role, count: length})' users.json

# Merge two objects (right wins)
jq -s '.[0] * .[1]' a.json b.json

# Delete a key
jq 'del(.password)' user.json

# Default when null
jq '.nickname // .name' user.json

Pipelines with curl and files

jq shines in shell pipelines. Fetch, filter, and write in one line:

curl -s https://api.example.com/users \
  | jq '[.[] | select(.active) | {id, email}]' \
  > active-users.json

Process many files with a loop, or use jq -s when you need all inputs as one array. Keep secrets out of shell history — prefer files or env vars over pasting tokens on the command line.

When browser tools are enough

jq is ideal for automation, CI, and large or repetitive jobs. For a one-time look at a payload, or when you want a table without writing a filter, browser-only tools are often simpler:

• JSON Formatter — pretty-print and validate.
• JSON Preview — inspect structure visually.
• Flatten JSON — nested objects → flatter shape.
• JSON to CSV / JSON to Excel — spreadsheet export without @csv boilerplate.

RividTech runs those steps entirely in your browser — nothing is uploaded. That matters for API dumps with personal data or tokens; see Why Browser-Only CSV Tools Are Safer for Your Data.

Getting started

Install jq, pretty-print a sample file with jq ., then try selecting one field and filtering an array. When you need a table for someone who will not run shell commands, pipe the result into a file and convert with JSON to CSV, or skip the CLI and start from JSON Formatter in the browser.