Public | Automated Build

Last pushed: 3 days ago
Short Description
jq.node - like jq but WAY MORE powerful (300+ helpers 🔥)
Full Description

jq.node - Become a shell hero, get super-power

jq.node is JavaScript and Lodash in your shell (along with the 300K+ npm modules). It's a powerful command-line JSON/string processor. It so easy it feels like cheating your inner-bearded-sysadmin.


I'm a huge fan of jq but it was so many times inconsistent and irritating. It sometimes felt like JavaScript but it was not.
jq.node is what jq should be in my opinion. First version was written in 25 lines of JavaScript code and was already way more powerful than jq, backed from day one by more than 300 helpers from Lodash FP.

Why jq.node? Why not jq?

  • jq.node does not try to implement its own expression language, it's pure JavaScript
  • no need to learn new operators or helpers, if you know lodash/fp, you know jq.node helpers
  • more powerful than jq will ever be jqn 'filter(has("email")) | groupBy(u =>"@")[1]) | csv'
  • through --require command option, jq.node leverages 300K+ npm modules. Hard to do more powerful than that!

Why jq? Why not jq.node?

  • performance matters more than feature set (in our current implementation jq is faster than jq.node, C vs JavaScript)
  • some features of jq are not currently implemented in jq.node
  • jq is a binary, jq.node is a NodeJS project (🌟 soon accessible through a docker image)

Install (NodeJS)

npm install jq.node -g

Shameless plug

CLI Usage

# the 4 commands below do the same thing
cat users.json | jqn 'filter(has("email")) | groupBy(function(u){return"@")[1]}) | csv'
cat users.json | jqn 'filter(has("email")) | groupBy(u =>"@")[1]) | csv'
cat users.json | jqn 'filter(has("email")) | groupBy(u => get("@"), 1)) | csv'
cat users.json | jqn 'filter(has("email")) | groupBy(flow(get("email"), split("@"), get(1))) | csv'

Note: the pipe | must always be surrounded by space to be understood by jqn as a pipe.


Be notified when a JSON value changed

while true; do curl -s | jqn 'property("task.status"), thru(a => exit(a === "IN_PROGRESS" ? 0 : 1))' || osascript -e 'display notification "Task done"'; sleep 5; done

Open every links from the clipboard

pbpaste | jqn -x -r opn 'split("\n") | forEach(opn)'
  • pbpaste, echoes clipboard content, MacOS only (use xclip or xsel in Linux)
  • opn is "a better node-open. Opens stuff like websites, files, executables. Cross-platform."

API Usage

jq.node exposes a node API for programmatic use. Require the jq function from the main module.

The arguments are jq(input, transformation, options, callback)

const { jq } = require('jq.node')

jq('20111031', 'thru(a => moment.utc(a, "YYYYMMDD"))', { rawInput: true, require: 'moment' }, function (err, result) {
  console.log(result) // "2011-10-31T00:00:00.000Z"

or with promises and async/await, via the bluebird module:

const { Promisify } = require('bluebird')
const { jq } = Promisify(require('jq.node'))

const result = await jq('20111031', 'thru(a => moment.utc(a, "YYYYMMDD"))', { rawInput: true, require: 'moment' })
console.log(result) // "2011-10-31T00:00:00.000Z"


CLI Shorthand CLI Longhand API Option Type Purpose
-h --help - - Display the help message and exit.
-j --json json boolean Force the result to be output as JSON. Without this, jqn outputs strings verbatim and non-strings as JSON.
-x --raw-input rawInput boolean
-c --color color boolean Colorize JSON (default true)
-r --require require array(string) * Require a NPM module <npm-module-name>.
-v --version - - Display the version and exit.
  • jq.node will automatically installs in a temporary folder it if its not available. The module will be available in the expression through its name (e.g. lodash for the lodash module). Module names that are invalid JavaScript variable names (e.g. js-yaml) will be exposed in camel-case format (e.g. jsYaml).

Currently supported

  • templateSettings, after, ary, assign, assignIn, assignInWith, assignWith, at, before, bind, bindAll, bindKey, castArray, chain, chunk, compact, concat, cond, conforms, constant, countBy, create, curry, curryRight, debounce, defaults, defaultsDeep, defer, delay, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, fill, filter, flatMap, flatMapDeep, flatMapDepth, flatten, flattenDeep, flattenDepth, flip, flow, flowRight, fromPairs, functions, functionsIn, groupBy, initial, intersection, intersectionBy, intersectionWith, invert, invertBy, invokeMap, iteratee, keyBy, keys, keysIn, map, mapKeys, mapValues, matches, matchesProperty, memoize, merge, mergeWith, method, methodOf, mixin, negate, nthArg, omit, omitBy, once, orderBy, over, overArgs, overEvery, overSome, partial, partialRight, partition, pick, pickBy, property, propertyOf, pull, pullAll, pullAllBy, pullAllWith, pullAt, range, rangeRight, rearg, reject, remove, rest, reverse, sampleSize, set, setWith, shuffle, slice, sortBy, sortedUniq, sortedUniqBy, split, spread, tail, take, takeRight, takeRightWhile, takeWhile, tap, throttle, thru, toArray, toPairs, toPairsIn, toPath, toPlainObject, transform, unary, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unset, unzip, unzipWith, update, updateWith, values, valuesIn, without, words, wrap, xor, xorBy, xorWith, zip, zipObject, zipObjectDeep, zipWith, entries, entriesIn, extend, extendWith, add, attempt, camelCase, capitalize, ceil, clamp, clone, cloneDeep, cloneDeepWith, cloneWith, conformsTo, deburr, defaultTo, divide, endsWith, eq, escape, escapeRegExp, every, find, findIndex, findKey, findLast, findLastIndex, findLastKey, floor, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, get, gt, gte, has, hasIn, head, identity, includes, indexOf, inRange, invoke, isArguments, isArray, isArrayBuffer, isArrayLike, isArrayLikeObject, isBoolean, isBuffer, isDate, isElement, isEmpty, isEqual, isEqualWith, isError, isFinite, isFunction, isInteger, isLength, isMap, isMatch, isMatchWith, isNaN, isNative, isNil, isNull, isNumber, isObject, isObjectLike, isPlainObject, isRegExp, isSafeInteger, isSet, isString, isSymbol, isTypedArray, isUndefined, isWeakMap, isWeakSet, join, kebabCase, last, lastIndexOf, lowerCase, lowerFirst, lt, lte, max, maxBy, mean, meanBy, min, minBy, stubArray, stubFalse, stubObject, stubString, stubTrue, multiply, nth, noConflict, noop, now, pad, padEnd, padStart, parseInt, random, reduce, reduceRight, repeat, replace, result, round, runInContext, sample, size, snakeCase, some, sortedIndex, sortedIndexBy, sortedIndexOf, sortedLastIndex, sortedLastIndexBy, sortedLastIndexOf, startCase, startsWith, subtract, sum, sumBy, template, times, toFinite, toInteger, toLength, toLower, toNumber, toSafeInteger, toString, toUpper, trim, trimEnd, trimStart, truncate, unescape, uniqueId, upperCase, upperFirst, each, eachRight, first are exposed from lodash/fp.
  • csv is exposed from json2csv
  • any of 300 000+ npm modules through the --require option!


  • jq time sh -c "cat messages.json | jq '.[].type'" 2ms user 0.01s system 95% cpu 0.028 total
  • jq.node time sh -c "cat messages.json | jqn 'map(\"type\")'" 170ms user 0.03s system 108% cpu 0.181 total


  • [x] Tests
  • [ ] Json-stream support
  • [x] Optionally colorize output (while still JSON compatible)

I accept pull-requests!


<!-- BACKERS/ -->



No maintainers yet! Will you be the first?


No sponsors yet! Will you be the first?

<span class="badge-patreon"><a href="" title="Donate to this project using Patreon"><img src="" alt="Patreon donate button" /></a></span>
<span class="badge-gratipay"><a href="" title="Donate weekly to this project using Gratipay"><img src="" alt="Gratipay donate button" /></a></span>
<span class="badge-flattr"><a href="" title="Donate to this project using Flattr"><img src="" alt="Flattr donate button" /></a></span>
<span class="badge-paypal"><a href="" title="Donate to this project using Paypal"><img src="" alt="PayPal donate button" /></a></span>
<span class="badge-bitcoin"><a href="" title="Donate once-off to this project using Bitcoin"><img src="" alt="Bitcoin donate button" /></a></span>


These amazing people have contributed code to this project:

<ul><li><a href="">Francois-Guillaume Ribreau</a> — <a href="" title="View the GitHub contributions of Francois-Guillaume Ribreau on repository fgribreau/jq.node">view contributions</a></li>
<li><a href="">chocolateboy</a> — <a href="" title="View the GitHub contributions of chocolateboy on repository fgribreau/jq.node">view contributions</a></li>
<li><a href="">Anton Ilin</a> — <a href="" title="View the GitHub contributions of Anton Ilin on repository fgribreau/jq.node">view contributions</a></li>
<li><a href="">Bruno Heridet</a> — <a href="" title="View the GitHub contributions of Bruno Heridet on repository fgribreau/jq.node">view contributions</a></li>
<li><a href="">Thales Mello</a> — <a href="" title="View the GitHub contributions of Thales Mello on repository fgribreau/jq.node">view contributions</a></li></ul>

<a href="">Discover how you can contribute by heading on over to the <code></code> file.</a>

<!-- /BACKERS -->

<!-- LICENSE/ -->


Unless stated otherwise all works are:

<ul><li>Copyright © <a href="">Francois-Guillaume Ribreau</a></li></ul>

and licensed under:

<ul><li><a href="">MIT License</a></li></ul>

<!-- /LICENSE -->

Docker Pull Command
Source Repository