TL;DR — Quick Summary

jq is a lightweight CLI tool for processing JSON. Filter, transform, query, and format JSON data from APIs, logs, and config files — all from your terminal.

jq makes JSON usable on the command line. Pipe any API response, log file, or config through jq and instantly extract, filter, and transform the data you need.

Installation

# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Arch Linux
sudo pacman -S jq

Usage

# Pretty-print JSON
echo '{"name":"Ada","age":36}' | jq .
curl -s api.github.com/users/octocat | jq .

# Extract fields
echo '{"name":"Ada","age":36}' | jq '.name'        # "Ada"
echo '{"name":"Ada","age":36}' | jq '.age'          # 36

# Nested fields
echo '{"user":{"name":"Ada","email":"a@b.com"}}' | jq '.user.email'

# Arrays
echo '[1,2,3]' | jq '.[0]'                          # 1
echo '[1,2,3]' | jq '.[]'                           # Each element

# Array of objects
echo '[{"name":"Ada"},{"name":"Bob"}]' | jq '.[].name'
echo '[{"name":"Ada"},{"name":"Bob"}]' | jq '.[0].name'

# Filter with select
echo '[{"name":"Ada","age":36},{"name":"Bob","age":25}]' | jq '.[] | select(.age > 30)'

# Build new objects
echo '{"first":"Ada","last":"Lovelace","age":36}' | jq '{full: (.first + " " + .last), age}'

# Length, keys, values
echo '{"a":1,"b":2}' | jq 'keys'                    # ["a","b"]
echo '[1,2,3]' | jq 'length'                        # 3

# Map and transform
echo '[1,2,3]' | jq '[.[] * 2]'                     # [2,4,6]

# Raw output (no quotes)
echo '{"name":"Ada"}' | jq -r '.name'               # Ada

# Slurp multiple inputs
echo '1' ; echo '2' ; echo '3' | jq -s '.'          # [1,2,3]

# Real-world: GitHub API
curl -s 'https://api.github.com/repos/jqlang/jq/releases' | \
  jq '.[0] | {tag: .tag_name, date: .published_at, downloads: [.assets[].download_count] | add}'

Summary

  • jq is sed/awk for JSON — filter, transform, query from the command line
  • Dot notation for field access, pipe chains for transformations
  • select() for filtering, map() for transforming, reduce for aggregating
  • Raw output (-r), compact (-c), slurp (-s) modes
  • Essential tool for working with APIs, logs, and config files