jq Manual

What it is

jq is a small, fast command-line program for reading and transforming JSON, often described as sed for JSON. This is its official manual, maintained by the jq project at jqlang.org. It documents every filter and function with examples you can try: the identity filter ., field access such as .name, iteration with .[], pipes inside jq, select for filtering, map, object and array construction, string interpolation, --arg for passing shell variables safely, and output options such as -r for raw strings.

Why it matters

JSON is everywhere a developer works: API responses, package files, cloud CLIs, logs and configuration. Without jq, people fall back on grep and cut, which break as soon as formatting changes, or write a throwaway script for every question. With jq you can answer questions such as "which users are admins?" or "what version is in this package file?" in one line, and use the same filters inside shell scripts.

How to learn it

The manual is complete but dense. A good approach:

1. Install jq from your package manager (apt, Homebrew and others package it).
2. Save a real JSON response from an API with curl.
3. Work through the manual's basic filters on that file: pretty-printing, field access, arrays, then select and map.
4. Build filters step by step, checking the output at each stage, as you would with a shell pipeline.
5. Use the online playground linked from the jq site to experiment without installing anything.

Is it worth it?

Yes. An hour with the basics pays back quickly, and jq is one of the few tools you will use across frontend, backend, DevOps and data work. You do not need the advanced parts, such as reduce or custom functions, until a real task asks for them.

Time needed

An hour or two for the everyday filters; the rest is reference material to look up when needed.

Common questions

Is jq installed by default? Often not. Install it with your package manager.

Can it edit files in place? Not directly. Write to a temporary file and move it, or use a tool built for editing JSON or YAML.

Is it free? Yes. jq is open source and the manual is free.