jq: The JSON CLI tool
Tags: json, jq, cli, shell
Published: 2020-02-08 23:49:03

---
title: jq: The JSON CLI tool
published: true
date: 2020-02-07 22:44:09 UTC
tags: json, jq, cli, shell
canonical_url: https://brian.olore.net/wp/2020/02/jq-the-json-cli-tool/
---

In Part 1 of [Working with JSON](https://dev.to/olore/working-with-json-in-javascript-29l8), we looked at how [lodash](https://lodash.com) makes manipulating JSON from JavaScript easy. Sometimes we’re working with chunks of JSON and it’s easier to deal with it from the shell. Scenarios like this include digging through log output and that (sometimes painful) time when you are first interacting with a new API.

Working with JSON in the shell is quicker and easier than trying to create a temporary file in your project or IDE, then writing some JavaScript code to open that file, parse its contents and scan for whatever it is you are looking for. Those of you that are skilled with the [Node.js](https://nodejs.org/) shell may disagree, but I’m determined to show you something you may not know and hopefully optimize your workflow too!

## Hello jq

[jq](https://stedolan.github.io/jq) is a CLI (command line interface) for working with JSON. It provides shell friendly features (piping, output redirection, etc) that make it feel as if it’s part of your operating system.   
  
To get started, install `jq` (on OSX)

```bash
brew install jq
```

Or [install it directly](https://stedolan.github.io/jq/download/) from the site

Running the `jq` command by itself will provide some usage info, but not a ton. You’re going to want to head to the [online manual](https://stedolan.github.io/jq/manual/), or the man page (`man jq`).

## Let’s see what `jq` can do!

`jq` is normally invoked by “piping” JSON data to it (using the `|` operator). This can be as simple as an echo command. Here we’ll use the [simplest filter](https://stedolan.github.io/jq/manual/#Basicfilters) `.`, “which copies jq’s input to its output”.

```javascript
echo '{"name": "Brian"}' | jq '.'
{
  "name": "Brian"
}
```

By default, jq will pretty print and colorize its output. Neat!

Because it works with pipes, you can also use commands like `curl` to get an API response, then pass it through `jq` like so:

```bash
curl -s https://swapi.co/api/people/1/ | jq '.'
{
  "name": "Luke Skywalker",
  "height": "172",
  "mass": "77",
  "hair_color": "blond",
  "skin_color": "fair",
  "eye_color": "blue",
  "birth_year": "19BBY",
  "gender": "male",
  "homeworld": "https://swapi.co/api/planets/1/",
  "films": [
    "https://swapi.co/api/films/2/",
    "https://swapi.co/api/films/6/",
    "https://swapi.co/api/films/3/",
    "https://swapi.co/api/films/1/",
    "https://swapi.co/api/films/7/"
  ],
  "species": [
    "https://swapi.co/api/species/1/"
  ],
  "vehicles": [
    "https://swapi.co/api/vehicles/14/",
    "https://swapi.co/api/vehicles/30/"
  ],
  "starships": [
    "https://swapi.co/api/starships/12/",
    "https://swapi.co/api/starships/22/"
  ],
  "created": "2014-12-09T13:50:51.644000Z",
  "edited": "2014-12-20T21:17:56.891000Z",
  "url": "https://swapi.co/api/people/1/"
}

```

As you can see this can be very useful when you need a quick sanity check of an API response structure, or if you forget if the key name is `eyeColor` or `eye_color`.

`jq` does more than pretty formatting! It let’s you slice & dice the JSON in many ways. For instance, let’s ask `jq` to return **Luke’s** `eye_color`

```bash
curl -s https://swapi.co/api/people/1/ | jq '.eye_color'
"blue"
```

Cool!

Thankfully, similar to [lodash.get](https://lodash.com/docs/4.17.15#get), if we ask for a path that doesn’t exist, it doesn’t die a horrible death

```bash
curl -s https://swapi.co/api/people/ | jq '.does.not.exist'
null
```

## Let’s get more advanced

What if we wanted to get the `eye_color` **of all the people** (on the first page of results)? Again, `jq` provides a syntax similar to [lodash.get](https://lodash.com/docs/4.17.15#get):

```bash
curl -s https://swapi.co/api/people/ | jq '.results[].eye_color'
"blue"
"yellow"
"red"
"yellow"
"brown"
"blue"
"blue"
"red"
"brown"
"blue-gray"
```

OK, let’s see if we can make it work a little harder. Let’s get the **`name` of all the people** (on the first page of results) **that have and `eye_color` of blue**?

```bash
curl -s https://swapi.co/api/people/ | jq '.results[] | select(.eye_color == "blue") .name'
"Luke Skywalker"
"Owen Lars"
"Beru Whitesun lars"
```

Sweet! This is where the power of `jq` really shines. There are many more powerful [filters, operators and functions](https://stedolan.github.io/jq/manual/#Builtinoperatorsandfunctions) I suggest you explore. Hopefully I was able to whet your appetite as this is just the tip of the iceberg of things you can do with `jq`.

## One more 

One last quick tip – this is the one I use for making sense of my JSON log messages all the time. If you are in OSX, you have the ability to access the clipboard from the shell using [pbcopy and pbpaste](http://osxdaily.com/2007/03/05/manipulating-the-clipboard-from-the-command-line/). So when I am working with JSON logs, from an application like Splunk, I copy the relevant JSON structure to the clipboard, then run it through `jq` like this:

```bash
pbpaste | jq '.'
```

The pretty printing alone is super useful. On top of that, you have all the great filtering commands to coerce an intimidating log message into a more approachable piece of data!

Special thanks to [https://swapi.co/](https://swapi.co/) for providing a fun API to play with!

The post [jq: The JSON CLI tool](https://brian.olore.net/wp/2020/02/jq-the-json-cli-tool/) appeared first on [The Brian Olore Story](https://brian.olore.net).