Skip to content
A "json" command for massaging JSON on your Unix command line.
JavaScript Makefile Python
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

A "json" command for massaging JSON on your Unix command line. This is a single-file node.js script.


  1. Get node and npm.

  2. npm install jsontool.

OR manually:

  1. Get the 'json' script and put it on your PATH somewhere (it is a single file with no external dependencies). For example:

    cd ~/bin
    curl -L > json
    chmod 755 json

Command-Line Usage

json -h:

Usage: <something generating JSON on stdout> | json [options] [lookups...]

Pipe in your JSON for nicer output. Or supply one or more `lookups`
to extract a subset of the JSON. HTTP header blocks (as from `curl -i`)
are skipped by default.

By default, the output is JSON-y: JSON, except for a simple string return
value, which is printed without quotes. Use '-j' or '-i' to override.

  -h, --help    print this help info and exit
  --version     print version of this command and exit
  -q, --quiet   don't warn if input isn't valid JSON
  -H            drop any HTTP header block
  -i            output using node's `sys.inspect`
  -j            output using `JSON.stringfy`, i.e. strict JSON
  -x, --experimental
                enable experimental features: '*' in lookup

  curl -s | json
  curl -s | json results

See <> for more.

Module Usage

Since v1.3.1 you can using "jsontool" as a node.js module:

var jsontool = require('jsontool');

However, so far the module API isn't that useful. This will improve in subsequent releases. For now the cli is the primary focus.


Using the Github API to look at node:

$ curl -s
{"repository":{"has_wiki":true,"forks":597,"language":"C++","pushed_at":"2011/03/18 15:19:24 -0700","homepage":"","open_issues":271,"fork":false,"has_issues":true,"url":"","created_at":"2009/05/27 09:29:46 -0700","size":20984,"private":false,"has_downloads":false,"name":"node","owner":"joyent","organization":"joyent","watchers":5584,"description":"evented I/O for v8 javascript"}}

Nice output by default:

$ curl -s | json
  "repository": {
    "has_wiki": true,
    "language": "C++",
    "homepage": "",
    "open_issues": 271,
    "fork": false,
    "has_issues": true,
    "url": "",
    "forks": 597,
    "created_at": "2009/05/27 09:29:46 -0700",
    "pushed_at": "2011/03/18 15:19:24 -0700",
    "size": 20984,
    "private": false,
    "has_downloads": false,
    "name": "node",
    "owner": "joyent",
    "organization": "joyent",
    "watchers": 5584,
    "description": "evented I/O for v8 javascript"

Say you just want to extract one value:

$ curl -s | json repository.open_issues

If you use curl -i to get HTTP headers (because perhaps they contain relevant information), json will skip those automatically:

$ curl -is | json repository
HTTP/1.1 200 OK
Server: nginx/0.7.67
Date: Fri, 11 Feb 2011 06:45:02 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
X-RateLimit-Limit: 60
ETag: "2fcb49428e91d0823acf453b15ccc0b5"
X-RateLimit-Remaining: 59
X-Runtime: 13ms
Content-Length: 398
Cache-Control: private, max-age=0, must-revalidate

  "forks": 514,
  "has_issues": true,
  "language": "C++",
  "url": "",
  "homepage": "",
  "has_downloads": false,
  "watchers": 4753,
  "fork": false,
  "created_at": "2009/05/27 09:29:46 -0700",
  "size": 15316,
  "private": false,
  "has_wiki": true,
  "name": "node",
  "owner": "joyent",
  "pushed_at": "2011/02/10 02:48:07 -0800",
  "description": "evented I/O for v8 javascript",
  "open_issues": 229

Or, say you are stuck with the headers in your pipeline, json -H will drop them:

$ curl -is | json -H repository.watchers

Here is an example that shows indexing a list. (The given "lookup" argument is basically JavaScript code appended, with '.' if necessary, to the JSON data and eval'd.)

$ curl -s | json 'repositories[2].description'
Connect is a middleware layer for Node.js

Test suite

make test

Note that the 'utf8' test fails with a V8 build before revision 5399, see I'm not sure exactly what node versions this corresponds to, but at least: broken in node 0.2.5 and working in node 0.4.0.

If you are stuck with an older node and don't want the utf8 failure in your face:

TEST_ONLY=-utf8 make test


  • consider a '*' syntax for running the subsequent lookup on all items in a list

Alternatives you might prefer

Something went wrong with that request. Please try again.