The Challenge of JSON in the Terminal
Modern APIs and cloud infrastructure exclusively communicate using JSON (JavaScript Object Notation). Whether you are pulling server statuses from AWS or retrieving weather data from a REST API, the output is almost always a deeply nested block of JSON text.
If you try to parse this output using traditional Linux text processing tools like grep, awk, or sed, you will quickly encounter a nightmare of unescaped quotes, trailing commas, and unpredictable formatting. These legacy tools were built for line-by-line text, not hierarchical data structures.
To interact with modern data from the command line, you need a modern tool: jq. jq is a lightweight, wildly powerful command-line JSON processor. It allows you to slice, filter, map, and transform JSON data with the same ease that grep handles plain text.
Installing jq
jq is not installed by default on most Linux distributions, but it is available in all major repositories.
- Ubuntu/Debian:
sudo apt install jq - CentOS/RHEL:
sudo yum install jq - macOS:
brew install jq
Basic Syntax: Formatting and Prettifying
Often, APIs return JSON as a single, massive, unreadable block of text (minified JSON). The most basic use of jq is simply to format (or “pretty print”) this output.
Assume we have an API endpoint returning user data. We can pipe the curl output directly into jq using the identity filter (.):
curl -s https://jsonplaceholder.typicode.com/users/1 | jq '.'The -s flag in curl silences the progress bar. The jq '.' command takes the raw input and prints it back out perfectly formatted with syntax highlighting and correct indentation.
Extracting Specific Values
Instead of printing everything, you usually want to extract a specific piece of data. You do this by chaining object keys together using standard dot notation.
Assume the JSON from the previous command looks like this:
{
"id": 1,
"name": "Leanne Graham",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net"
}
}To extract just the user’s name:
curl -s https://api.example.com/users/1 | jq '.name'To extract the company name, which is nested inside the company object, you chain the keys:
curl -s https://api.example.com/users/1 | jq '.company.name'Working with Arrays
If an API returns a list (an array) of users rather than a single user, you must use array iterators ([]).
Assume the API returns an array containing 10 users. To extract the name of the first user (arrays are zero-indexed):
curl -s https://api.example.com/users | jq '.[0].name'To extract the names of every user in the array and print them as a clean list:
curl -s https://api.example.com/users | jq '.[].name'Filtering Data (The select Function)
jq can also act as a powerful search engine using the select() function.
Suppose you have a massive JSON array of 1,000 users, and you only want to see the records of users whose “status” is “active”.
curl -s https://api.example.com/users | jq '.[] | select(.status == "active")'This command iterates through the array (.[]), pipes each object into the select function (|), and only prints the objects where the condition is true.
Conclusion
For DevOps engineers, system administrators, and backend developers, mastering jq is no longer optional. It is the definitive bridge between the rigid, text-based world of the Linux terminal and the dynamic, object-oriented reality of modern web APIs.