jq - Master JSON Processing in the Terminal

You curl an API and get a wall of JSON. You need just one field. Or you need to transform the data. Or filter an array. jq is a lightweight command-line JSON processor that makes working with JSON as easy as working with text.

🔧

sed for JSON

jq is like sed, awk, and grep combined - but for JSON. Slice, filter, map, and transform structured data with a powerful yet intuitive syntax.

JSON In, JSON Out

jq takes JSON input, applies filters, and outputs transformed JSON. It's perfect for API responses, config files, and data pipelines:

jq filters transform JSON input into exactly the output you need

Key Features

🔎

JSON Filtering

Extract specific fields, filter arrays by conditions, navigate nested objects with simple syntax

🔄

Data Transformation

Reshape JSON, rename keys, combine fields, convert formats - all in a single pipeline

⌨

Pipe-Friendly

Chain with curl, cat, kubectl, or any command. Standard Unix pipes just work

💻

Programming Power

Variables, conditionals, functions, reduce - jq is a complete programming language for JSON

Practical Examples

Basic Filters - extract and navigate JSON:

Terminal - Basic jq usage

# Pretty print JSON
curl -s api.example.com/data | jq '.'

# Get a specific field
echo '{"name": "Alice", "age": 30}' | jq '.name'
# Output: "Alice"

# Get raw string (no quotes)
echo '{"name": "Alice"}' | jq -r '.name'
# Output: Alice

# Access nested fields
echo '{"user": {"profile": {"email": "a@b.com"}}}' | jq '.user.profile.email'
# Output: "a@b.com"

# Get array element by index
echo '{"items": ["a", "b", "c"]}' | jq '.items[0]'
# Output: "a"

# Get all array elements
echo '{"items": ["a", "b", "c"]}' | jq '.items[]'
# Output:
# "a"
# "b"
# "c"

Array Operations - filter, map, and transform arrays:

Terminal - Array operations

# Sample data
DATA='{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Carol", "age": 35}]}'

# Get all names
echo $DATA | jq '.users[].name'
# Output: "Alice" "Bob" "Carol"

# Filter: users older than 28
echo $DATA | jq '.users[] | select(.age > 28)'
# Output: {"name": "Alice", "age": 30}
#         {"name": "Carol", "age": 35}

# Map: get just names of filtered users
echo $DATA | jq '[.users[] | select(.age > 28) | .name]'
# Output: ["Alice", "Carol"]

# Sort by age
echo $DATA | jq '.users | sort_by(.age)'

# Get first/last element
echo $DATA | jq '.users | first'
echo $DATA | jq '.users | last'

# Count elements
echo $DATA | jq '.users | length'
# Output: 3

# Sum ages
echo $DATA | jq '[.users[].age] | add'
# Output: 90

Object Construction - create new JSON structures:

Terminal - Building new JSON

# Create new object structure
echo '{"firstName": "Alice", "lastName": "Smith", "age": 30}' | jq '{
  fullName: (.firstName + " " + .lastName),
  isAdult: (.age >= 18)
}'
# Output: {"fullName": "Alice Smith", "isAdult": true}

# Transform array of objects
echo '[{"id": 1, "name": "A"}, {"id": 2, "name": "B"}]' | jq 'map({
  key: .id,
  value: .name
})'
# Output: [{"key": 1, "value": "A"}, {"key": 2, "value": "B"}]

# Convert to key-value object
echo '[{"id": 1, "name": "A"}, {"id": 2, "name": "B"}]' | jq 'map({(.name): .id}) | add'
# Output: {"A": 1, "B": 2}

# Add/modify fields
echo '{"name": "Alice"}' | jq '. + {age: 30, city: "NYC"}'
# Output: {"name": "Alice", "age": 30, "city": "NYC"}

# Delete fields
echo '{"a": 1, "b": 2, "c": 3}' | jq 'del(.b)'
# Output: {"a": 1, "c": 3}

Real-World API Example - process API responses:

Terminal - Working with APIs

# Get GitHub user repos, extract name and stars
curl -s "https://api.github.com/users/torvalds/repos" | jq '
  .[] | {name: .name, stars: .stargazers_count}
' | head -20

# Get top 5 repos by stars
curl -s "https://api.github.com/users/torvalds/repos" | jq '
  sort_by(.stargazers_count) | reverse | .[0:5] | .[].name
'

# Create a summary
curl -s "https://api.github.com/users/octocat" | jq '{
  username: .login,
  repos: .public_repos,
  followers: .followers,
  profile: .html_url
}'

# Use with kubectl for Kubernetes
kubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'

# Parse Docker inspect output
docker inspect mycontainer | jq '.[0].NetworkSettings.IPAddress'

# AWS CLI + jq
aws ec2 describe-instances | jq '.Reservations[].Instances[] | {id: .InstanceId, state: .State.Name}'

Why Developers Love It

✓ Instant Pretty Printing - curl ... | jq '.' turns unreadable JSON into formatted output
✓ No Dependencies - Single binary, works everywhere. No Python, Node, or runtime needed
✓ Pipeline Powerhouse - Chains perfectly with curl, cat, kubectl, aws-cli, and any JSON-outputting tool
✓ Faster Than Scripts - No need to write Python just to extract a field from JSON
✓ Scriptable - Use in bash scripts for config parsing, data transformation, and automation
✓ Color Output - Syntax highlighting makes JSON easy to read in terminal

Cheatsheet

Quick reference for common jq patterns:

Pattern	Example	Description
`.`	`jq '.'`	Pretty print / identity
`.field`	`jq '.name'`	Get field value
`.a.b.c`	`jq '.user.profile.email'`	Nested field access
`.[]`	`jq '.items[]'`	Iterate array elements
`.[n]`	`jq '.[0]'`	Array index
`select()`	`jq '.[] \| select(.age > 18)'`	Filter by condition
`map()`	`jq 'map(.name)'`	Transform each element
`sort_by()`	`jq 'sort_by(.date)'`	Sort array by field
`length`	`jq '.items \| length'`	Count elements
`keys`	`jq 'keys'`	Get object keys
`add`	`jq '[.items[].price] \| add'`	Sum array values
`-r`	`jq -r '.name'`	Raw output (no quotes)

Pro Tips

🎯

Use -r for Shell Scripts

The -r flag outputs raw strings without quotes. Essential when piping to other commands: NAME=$(echo '{"name":"Alice"}' | jq -r '.name')

📋

Handle Null Values Safely

Use // for defaults: jq '.missing // "default"'. Or use ? for optional access: jq '.user?.name?'

💾

Read From Files

Use jq '.' config.json directly, or jq --slurpfile data file.json '.items = $data' to read files as variables.

📈

Convert to Other Formats

Output as CSV: jq -r '.[] | [.name, .age] | @csv'. Or TSV: @tsv. Even URI encoding: @uri

🔌

Use jq Playground Online

Test filters at jqplay.org before using in scripts. Paste your JSON, experiment with filters, see results instantly.

Getting Started

1

Install jq

macOS: brew install jq | Ubuntu: apt install jq | Windows: choco install jq
2

Try Pretty Printing

Run curl -s api.github.com/users/octocat | jq '.' to see formatted JSON with colors.
3

Extract a Field

Try curl -s api.github.com/users/octocat | jq '.login, .followers' to get specific fields.
4

Explore the Manual

Run jq --help or visit jq manual for comprehensive documentation.

Master JSON Processing

Stop writing scripts just to parse JSON. jq makes command-line JSON processing fast and intuitive.

Get jq

Launch Offer