jq

Command-line JSON processor

Data & JSON Text Processing Development linuxmacoswindows C MIT

Description

jq is a lightweight and flexible command-line JSON processor. It's like sed for JSON data - you can use it to slice, filter, map, and transform structured data with the same ease that sed, awk, grep, and friends let you play with text.

Install

homebrewbrew install jq

aptsudo apt install jq

pacmansudo pacman -S jq

AI Summary

The standard tool for querying and transforming JSON on the command line. Pipe JSON in, get filtered/transformed JSON or text out. Essential for working with APIs and config files.

Capabilities

+ Query nested JSON structures with dot notation
+ Filter arrays with select expressions
+ Transform and reshape JSON documents
+ Format and pretty-print JSON
+ Construct new JSON from parts
+ String interpolation and formatting
+ Mathematical operations on numeric values

Use When

→ Extracting fields from API responses
→ Transforming JSON between formats
→ Pretty-printing JSON for readability
→ Filtering and querying JSON arrays
→ Building JSON payloads in shell scripts

Avoid When

x Processing non-JSON data (use awk/sed instead)
x Very large JSON files that don't fit in memory
x Need full programming language features (use Python/Node)

Usage Patterns

Extract a field from JSON

echo '{"name":"test"}' | jq '.name'

Extracts the 'name' field value

Pretty-print JSON

curl -s api.example.com/data | jq .

Formats raw JSON with colors and indentation

Filter an array

jq '.[] | select(.status == "active")' data.json

Returns only objects where status is active

Extract raw strings (no quotes)

jq -r '.name' data.json

Outputs the value without JSON string quotes

Input / Output

stdin: JSON data

stdout: Filtered/transformed JSON or text

Exit codes:

0 Success

1 Usage error

2 Compile error in filter

3 System error

5 No valid result (with -e flag)

Typical Pipelines

curl -s api.github.com/repos/owner/repo | jq '.stargazers_count'

docker inspect container | jq '.[0].NetworkSettings.IPAddress'

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

Related Tools

yq alternative

yq provides similar functionality for YAML

fx alternative

fx is an interactive JSON viewer and processor

ripgrep complementary

rg --json outputs JSON that jq can process

View AGENTS.md for jq