Querying JSON data at the command line with ‘jq’

Oh Dear monitors your entire site, not just the homepage. We crawl and search for broken pages and mixed content, send alerts when your site is down and notify you on expiring SSL certificates.

Start your free 10 day trial! »

Profile image of Mattias Geniar

Mattias Geniar, November 17, 2015

Follow me on Twitter as @mattiasgeniar

If you’re not familiar with the tool yet, I’d like to introduce you to jq: a lightweight and flexible command-line JSON processor.

The jq tool us super useful to query JSON data at the command line of a Linux (or Mac OSX) machine as a sysadmin.


Depending on your OS, it’s going to be:

# CentOS, Red Hat
$ yum install jq

# Debian, Ubuntu
$ apt-get install jq

# Mac with Homebrew
$ brew install jq


I’ll be showing you a quick usage with ElasticSearch. It’s a service that has, for this demo, a very simple HTTP call you can make that returns a JSON response.

Here’s the raw data:

$ curl -s -XGET 'http://localhost:9200/_cluster/health?pretty=true'
  "cluster_name" : "your_cluster_name",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 10,
  "active_shards" : 10,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 10

We get a nicely formatted JSON reply. Sure, you can grep, sed and awk this output and get the values you want, but there’s a cleaner solution out there, called jq. Whether it’s simpeler depends entirely on you and what you’re more comfortable with.

If I want the output of the “status” key and want to see its value, I can do this with jq:

$ curl -s -XGET 'http://localhost:9200/_cluster/health?pretty=true' | jq -s .[0].status

Let’s break it down a bit:

  • jq: the binary you just installed
  • -s: read the input stream (the curl before the pipe) and process it as a whole
  • .[0].status: process the entire response (.), take the first element from the JSON array (.0) and give me the status key (.status)

This example just touches the basics of jq, if you want to parse more complex JSON values and do some calculations or output manipulations, check out the `jq` manual and documentations.

Want to subscribe to the cron.weekly newsletter?

I write a weekly-ish newsletter on Linux, open source & webdevelopment called cron.weekly.

It features the latest news, guides & tutorials and new open source projects. You can sign up via email below.

No spam. Just some good, practical Linux & open source content.