Start Using The jq Tool For JSON in the terminal
Tags: javascript, webdev, codenewbie
Published: 2021-08-03 14:00:11

The [jq command line tool](https://stedolan.github.io/jq/) is definitely one of my favorite finds. If you've ever "prettified" JSON by copying it into VScode, I'm about to save you like 6 seconds by showing how to format (and even filter!) JSON right in the terminal.

> [Download page](https://stedolan.github.io/jq/download/), but on mac it's easiest to `brew install jq` if you already have [homebrew](https://brew.sh) installed

## Pretty print json
First, look at the difference of this command line output:
![Unorganized JSON terminal output vs. beautifully formatted JSON output](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5w154nho60i6p6g0w1tk.png)

It's night and day. The way to do this is couldn't be simpler, just [pipe some output](https://www.codecademy.com/learn/learn-the-command-line/modules/learn-the-command-line-redirection/cheatsheet) into `jq`:

```bash
# from a curl
curl -s https://api.spacexdata.com/v3/launches/latest | jq
# from a file 
cat raw.json | jq
```

## Filtering your output
Besides nicely formatting your output, jq can also do some object and array filtering. Check out the [official docs](https://stedolan.github.io/jq/tutorial/), but here's the tl:dr; on the handiest features.

### Grab specific property or index
Sometimes your data isn't at the top level:

```bash
curl -s https://swapi.dev/api/people/ | jq
{
  "count": 82,
  "next": "http://swapi.dev/api/people/?page=2",
  "previous": null,
  "results": [
    {
      "name": "Luke Skywalker",
      "height": "172",
# ...
```

If we only care about the `results` array, we can specify that:
 
```bash
curl -s https://swapi.dev/api/people/ | jq .results
[
  {
    "name": "Luke Skywalker",
    "height": "172",
# ...
```

That `jq .results` tells `jq` to show us the `results` property. That `.` stands for the current input, in this case the curl response. If the response is already an array, you'd use `.[0]`, or if a property points to an array, you'd put the property name and then the index:

```bash 
curl -s https://swapi.dev/api/people/ | jq .results[0]
{
  "name": "Luke Skywalker",
  "height": "172",
# ...
```

### Format objects in an array
We can filter for specific properties in each object pretty easily:

```bash 
curl -s https://swapi.dev/api/people/ | jq '.results[] | .name'
"Luke Skywalker"
"C-3PO"
# ...
```

Instead of using an index, we just use `[]` to say we want the whole array. And by using the `|` pipe we are saying "pass each item in the array into this filter and show only the select properties". Two important things here: the whole argument needs to be wrapped in a string, and the second `.` now refers to each object getting piped in, not the original response.

### Multiple properties
You can select more than one property by using comma separated values, but it's not super clean:
```bash
curl -s https://swapi.dev/api/people/ | jq '.results[] | .name, .mass'
"Luke Skywalker"
"77"
"C-3PO"
"75"
# ...
```
Instead, I recommend the object syntax:

```bash 
curl -s https://swapi.dev/api/people/ | jq '.results[] | {name: .name, character_mass: .mass, vehicles: .vehicles[0] }'
{
  "name": "Luke Skywalker",
  "character_mass": "77",
  "vehicles": "http://swapi.dev/api/vehicles/14/"
}
{
  "name": "C-3PO",
  "character_mass": "75",
  "vehicles": null
}

```

The name of the property can be anything, and keep in mind that you can go as deep as you want. Finally, you'll notice that these objects are just floating in space. If you wanted to output this to a JSON file that's not good, so we can wrap the entire string argument in an array to get an array output:

```bash
curl -s https://swapi.dev/api/people/ | jq '[.results[] | {name: .name, character_mass: .mass, vehicles: .vehicles[0]}]'
[
  {
    "name": "Luke Skywalker",
    "character_mass": "77",
    "vehicles": "http://swapi.dev/api/vehicles/14/"
  },
  {
    "name": "C-3PO",
    "character_mass": "75",
    "vehicles": null
  },
# ...
```

And there you go! That's probably 90% of what you'll use this little tool to do. But still, check out the jq site for [more methods](https://stedolan.github.io/jq/manual/) and an [online playground](https://jqplay.org).

happy coding everyone,

mike