The Problem with JSON in the Terminal
Modern APIs, configuration files, and cloud services (like AWS or Google Cloud) almost exclusively output data in JSON (JavaScript Object Notation) format. JSON is excellent for computers to read because it is highly structured. However, it can be a nightmare for humans to read in a raw Linux terminal.
If you run a command like curl https://api.github.com/repos/torvalds/linux, the terminal will instantly flood your screen with a massive, unformatted block of text. Trying to use traditional text-processing tools like grep or awk to extract a specific value (like the number of “stargazers”) from a complex, nested JSON structure is incredibly difficult and prone to errors.
The solution is jq, a lightweight and flexible command-line JSON processor. It is often described as “sed for JSON.”
Step 1: Installing jq
While standard tools like grep come pre-installed on every Linux distribution, jq is usually a third-party package. You must install it first.
- Debian/Ubuntu:
sudo apt install jq - RHEL/CentOS/Fedora:
sudo dnf install jq - Arch Linux:
sudo pacman -S jq
Step 2: Pretty-Printing JSON
The most basic and frequently used feature of jq is its ability to take an ugly, minimized block of JSON and “pretty-print” it—adding proper indentation, line breaks, and color-coding to make it instantly readable.
If you have a file named data.json that is just one long line of text, you can format it by passing it through jq using a single period (.), which represents the entire JSON object.
cat data.json | jq '.'
Alternatively, if you are fetching data from a live API via curl, simply pipe the output directly into jq:
curl -s https://api.github.com/repos/torvalds/linux | jq '.'
The output will be transformed from a wall of text into a beautifully formatted, hierarchical tree.
Step 3: Extracting Specific Values
Pretty-printing is helpful, but the real power of jq is extraction. Imagine the GitHub API returns the following simplified structure:
{
"name": "linux",
"owner": {
"login": "torvalds"
},
"stargazers_count": 150000
}
If you write a bash script and you only want to extract the number of stars, you can traverse the JSON keys using dot notation.
curl -s https://api.github.com/repos/torvalds/linux | jq '.stargazers_count'
The command will strip away everything else and output exactly 150000.
Step 4: Navigating Nested Objects
If the data you need is buried inside another object, you just chain the keys together.
In the example above, the creator’s username (“torvalds”) is located inside the “owner” object. To extract it, you type:
curl -s https://api.github.com/repos/torvalds/linux | jq '.owner.login'
This will output "torvalds" (including the quotation marks). If you want the raw text without the quotes (useful for injecting the result directly into a bash variable), add the -r (raw) flag:
curl -s https://api.github.com/repos/torvalds/linux | jq -r '.owner.login'
Step 5: Working with Arrays
JSON frequently uses arrays (lists of items enclosed in square brackets []). Imagine an API returns a list of users:
[
{"name": "Alice", "role": "admin"},
{"name": "Bob", "role": "user"}
]
To extract the name of the very first person in the list, you target index 0:
cat users.json | jq '.[0].name' (Outputs: “Alice”)
If you want to extract all the names and ignore the roles, you iterate through the entire array using empty brackets [] before specifying the key:
cat users.json | jq '.[].name'
This will output:
“Alice”
“Bob”