jq: 10 Essential Commands for Linux JSON Processing

Stop Parsing JSON by Hand

If you work with APIs, config files, or any modern web service, you deal with JSON every day. Reading through nested structures by eye is slow. Grep and awk work for simple cases but fall apart fast. That is where the jq command comes in.

jq is a JSON processor for the terminal. Think of it like sed or awk, but built specifically for JSON data. You pipe JSON in, write a filter, and get structured output back. I use it daily for debugging APIs, extracting values from configs, and transforming data between formats.

In this guide I will walk through 10 practical uses for the jq command. By the end you will be able to parse, filter, and reshape JSON right from your shell.

What Is the jq Command?

jq was created by Stephen Dolan and is now maintained under jqlang on GitHub. It is written in C with zero runtime dependencies. You give it JSON on stdin, apply a filter expression, and it writes the result to stdout. The syntax takes some getting used to, but the power is worth it.

The jq command supports everything from simple field lookups to complex transformations with conditionals and custom functions. It handles small one-liners and big scripted pipelines equally well.

Installing the jq Command

jq is in every major package manager. On Debian or Ubuntu you run:

sudo apt install jq -y

On Fedora or RHEL:

sudo dnf install jq

On macOS with Homebrew:

brew install jq

That is it. No config files, no daemon, no service. Install and go.

10 Essential jq Command Examples

1. Pretty-Print JSON

The simplest use of the jq command is formatting raw JSON into something readable. Many APIs return minified JSON that is impossible to scan by eye.

curl -s https://api.github.com/repos/jqlang/jq | jq '.'

The dot is a filter that means “pass everything through.” jq formats it with proper indentation and colorized output by default. I pipe API responses through this constantly.

2. Access Object Properties

To get a specific field from a JSON object, use .fieldname. Say you want just the description of a GitHub repo:

curl -s https://api.github.com/repos/jqlang/jq | jq '.description'

jq returns the value with quotes. Add the -r flag for raw output without surrounding quotes:

curl -s https://api.github.com/repos/jqlang/jq | jq -r '.description'

This is how you extract single values from API responses for use in scripts.

3. Access Array Elements

JSON arrays use zero-based indexing. To get the first element from an array:

echo '[{"name":"Alice"},{"name":"Bob"}]' | jq '.[0]'

To get all names from every object in an array:

echo '[{"name":"Alice"},{"name":"Bob"}]' | jq '.[].name'

The .[] iterator loops over every element. You can slice arrays too: .[0:2] gets the first two items.

4. Build Objects with Custom Keys

You can reshape JSON completely with the jq command. Say you want to rename fields or build a new structure:

cat data.json | jq '{username: .name, email: .email}'

This creates a new object with keys you choose, pulling values from the input. I use this to normalize data from different APIs into a standard format before loading into a database.

5. Filter Arrays with select()

The select() function filters array elements by a condition. Get only repos that are not forks:

curl -s https://api.github.com/users/jqlang/repos | jq '.[] | select(.fork == false) | .name'

You can combine conditions. Find repos with more than 100 stars that are not archived:

curl -s https://api.github.com/users/jqlang/repos | jq '.[] | select(.stargazers_count > 100 and .archived == false) | .name'

This is the most powerful feature of the jq command for data analysis.

6. Count Items with length

The length function works on strings, arrays, and objects. Count how many issues are open on a repo:

curl -s https://api.github.com/repos/jqlang/jq/issues | jq 'length'

Count the number of keys in an object:

cat data.json | jq '. | length'

It is a simple utility but I use it all the time for quick stats on API responses.

7. Transform Values with map()

Need to apply an operation to every element in an array? Use map(). Convert an array of objects to an array of names:

cat users.json | jq 'map(.name)'

Multiply every number in an array by 2:

echo '[1,2,3,4]' | jq 'map(. * 2)'

map() is especially useful when you need to transform one API response format into another.

8. Merge Objects with the Comma Operator

jq uses the comma as a union operator. Combine two objects or add extra fields:

echo '{"name":"Alice"}' | jq '{name, role: "admin"}'

You can merge input data with computed values. This is handy for adding metadata or timestamps before sending data to another service.

9. Use Variables for Reusable Queries

The jq command supports variables with the --arg flag. Pass shell variables into your filter:

min_stars=500
curl -s https://api.github.com/users/jqlang/repos | jq --arg min "$min_stars" '.[] | select(.stargazers_count > ($min | tonumber)) | .name'

This keeps your filters clean and your data dynamic. No more hardcoding values inside JSON queries.

10. Output Raw Strings to CSV

Combine -r with @csv to generate CSV output from JSON. Convert a list of repos to a simple CSV:

curl -s https://api.github.com/users/jqlang/repos | jq -r '.[] | [.name, .stargazers_count, .language] | @csv'

jq handles the quoting and escaping. This saves me from writing a separate script every time I need to convert JSON data to a spreadsheet-friendly format.

Putting It All Together

Here is a real workflow. Fetch the latest releases for a GitHub repo, filter to non-prerelease versions, and output just the tag name and date as CSV:

curl -s https://api.github.com/repos/jqlang/jq/releases | \
  jq -r '.[] | select(.prerelease == false) | [.tag_name, .published_at] | @csv'

One command replaces what would take 15 lines of Python or a dozen grep/awk/sed invocations. That is the value of the jq command in your daily toolkit.

Why You Should Learn the jq Command

JSON is everywhere. Kubernetes configs, Docker API responses, Terraform state files, CI/CD pipeline outputs, web service payloads. Every time you touch one of these, the jq command saves you from writing throwaway scripts.

Check out the official jq documentation for the full language reference. The jq GitHub repository has the source and issue tracker. For a deeper dive, the DigitalOcean jq tutorial covers advanced use cases.

If you liked this guide, you might also enjoy my tutorial on ripgrep for text searching, bat as a cat replacement, or eza for modern file listings. All part of the modern Linux CLI toolkit.