Categories
Posts

jq, Command Line JSON Processor

I love being able to make quick web API calls using cURL, and most of the time I get back JSON. Unfortunately it isn’t easy to manipulate JSON strings with traditional Unix utilities. That is the void that jq fills.

A basic example is pulling a single value out of the JSON string. Given a JSON string in a file called test.json that looks like:

[sourcecode lang=”javascript”]
{
"foo": 42,
"bar": "less interesting data"
}
[/sourcecode]

you can easily pull out the value for ‘foo’ with:

[sourcecode]
> cat test.json | jq ‘.foo’
> 42
[/sourcecode]

Asking for the value of ‘bar’ will return something you might not expect at first:

[sourcecode]
> cat test.json | jq ‘.bar’
> "less interesting data"
[/sourcecode]

By default jq will attempt to output JSON, which is why you end up with the quotes around the string. To get the string value without the quotes you’ll need to use ‘-r’, or ‘–raw-output’:

[sourcecode]
> cat test.json | jq -r ‘.bar’
> less interesting data
[/sourcecode]

These are trivial examples, the tutorial walks you through more features and the manual describes the filtering and other capabilities in detail, with examples.

Binaries for a number of platforms are available. Source code is hosted at https://github.com/stedolan/jq under an MIT style open source license.

Given the continued popularity of JSON it would be nice to see jq included as part of a standard Unix install; alongside sed, awk, and grep. It has proven useful enough to me already that I’ve started installing it on the systems that I regularly use.