jq — Lightweight Command-Line JSON Processor

What it is

jq is a lightweight command-line tool for processing JSON data. Think of it as sed for JSON -- it takes JSON input, applies filters and transformations using a concise expression language, and outputs the result. jq handles extraction, filtering, mapping, and restructuring of JSON without writing a full program.

jq is essential for anyone working with APIs, configuration files, or data pipelines in the terminal. Developers, DevOps engineers, and data analysts use it daily to inspect API responses, transform log output, and process CI/CD artifacts.

How it saves time or tokens

Without jq, extracting a field from a JSON API response requires writing a script in Python or Node.js. With jq, a single pipe does the job: curl api | jq '.data.items[].name'. This eliminates the overhead of writing, running, and maintaining throwaway scripts. For AI workflows, jq is invaluable for post-processing LLM API responses -- extracting token counts, filtering results, or reformatting output for downstream tools.

How to use

1. Install jq: brew install jq (macOS) or sudo apt install jq (Linux).
2. Pipe JSON into jq: echo '{"name":"Alice"}' | jq .name.
3. Use filters to extract, transform, or restructure data.
4. Combine with curl for API inspection: curl -s api.example.com | jq '.results[]'.

Example

# Pretty-print JSON
echo '{"name":"Alice","age":30}' | jq .

# Extract nested fields
curl -s https://api.github.com/repos/jqlang/jq | jq '{name: .name, stars: .stargazers_count}'

# Filter array elements
echo '[{"status":"ok"},{"status":"error"}]' | jq '.[] | select(.status == "error")'

# Transform structure
echo '{"users":[{"name":"A","age":25},{"name":"B","age":30}]}' | jq '.users | map({name, adult: (.age >= 18)})'

Related on TokRepo

• AI tools for automation -- discover command-line tools for automating data workflows.
• Automation tools collection -- browse CLI utilities curated on TokRepo.

Common pitfalls

• jq expressions use single quotes on Unix shells. On Windows PowerShell, you need double quotes with escaped internals, which can be confusing.
• The .[] operator iterates array elements but produces multiple outputs, not an array. Wrap in [.[] | ...] to collect results back into an array.
• jq error messages can be cryptic. When a filter fails silently, add ? (try operator) or use --debug-dump-disasm to trace execution.