JSON is everywhere on the command line - API responses, config files, tool output - and reading it as a wall of text is miserable. jq is the tool that turns that wall into something you can query. It's a small, fast processor with a surprisingly powerful language for slicing, filtering, mapping, and reshaping JSON, and it composes into pipelines like any good Unix tool.
A Query Language for JSON
The basics cover most of what you need day to day - pull a field, filter a list, reshape objects:
# Pretty-print and pull a nested field
curl -s api/endpoint | jq '.data.items'
# Filter a list and reshape each item
jq '.[] | select(.active) | {id, name}' data.json
# Get just the titles as raw strings
jq -r '.data[].attributes.title' nodes.json
From One-Liners to Real Programs
jq scales from a quick .field up to genuine transformations with variables, functions, and conditionals. For the common cases it's a two-second one-liner; for the hard ones it's still the right tool.
Rough Edges and Limitations
- The syntax has a learning curve. Simple queries are obvious; advanced ones need the manual and some trial and error.
- Errors can be terse. A malformed filter sometimes reports less than you'd like.
- JSON only. For YAML or XML you'll want a sibling tool like yq.
Once jq is in your fingers, working with any JSON API from the shell stops being a chore and becomes a pipe.
Internal link suggestion: link "any API or file" to the yq post, its YAML counterpart, or to the Repomix or JSON:API context of this project.