FX(1)

💅 FX(1) 💅

okay bestie so this is fx, from the User Commands manual ✨ — like, the whole page header is FX(1) and the manual name is literally User Commands, but we're not gonna make a whole thing of it. this is the fx page. it's the command-line JSON processing tool and it is, genuinely, iconic 🎀

🌸 NAME 🌸

fx — the command-line JSON processing tool. that's it. that's the vibe. 🦋

✨ SYNOPSIS ✨

fx [code ...]

so fx has two modes: cli and interactive 🫶

to start interactive mode, you literally just pipe any JSON into it:

$ curl ... | fx

or you can pass a filename as the first parameter:

$ fx my.json

and if any argument was passed, fx will apply it and print to stdout. simple as that 💅

🔥 DESCRIPTION 🔥

start interactive mode by not passing any arguments at all:

$ curl ... | fx

or by passing a filename as the first argument:

$ fx data.json

pass a few JSON files at once, why not:

$ cat foo.json bar.json baz.json | fx .message

use the full power of JavaScript (not me being obsessed with a one-liner):

$ curl ... | fx '.filter(x => x.startsWith("a"))'

get access to all lodash (or ramda, etc) methods by using a .fxrc file:

$ curl ... |
> fx '_.groupBy("commit.committer.name")' '_.mapValues(_.size)'

update JSON using the spread operator, main character energy:

$ echo '{"count": 0}' | fx '{...this, count: 1}'
{
  "count": 1
}

extract values from maps:

$ fx commits.json | fx .[].author.name

print formatted JSON to stdout:

$ curl ... | fx .

pipe a JSON logs stream into fx:

$ kubectl logs ... -f | fx .message

and bestie. try this one. just trust me:

$ fx --life

---

🧚 USAGE 🧚

💜 ANONYMOUS FUNCTION

use an anonymous function as the reducer, which gets the JSON and processes it:

$ echo '{"foo": [{"bar": "value"}]}' | fx 'x => x.foo[0].bar'
value

💜 BINDING

if you don't pass an anonymous function param => ..., your code gets automatically transformed into an anonymous function. and you can get access to the JSON through the this keyword:

$ echo '{"foo": [{"bar": "value"}]}' | fx 'this.foo[0].bar'
value

💜 DOT

it's possible to omit the this keyword entirely:

$ echo '{"foo": [{"bar": "value"}]}' | fx .foo[0].bar
value

and if a single dot is passed, the input JSON gets formatted but is otherwise unaltered:

$ echo '{"foo": "bar"}' | fx .
{
  "foo": "bar"
}

💜 MAP

one of the frequent operations is mapping some function over an array — for example, extracting some values. say you have:

[
  {
    "author": {
      "name": "antonmedv"
    }
  },
  {...},
  ...
]

and we want to collect the names of each object in the array. we can do it by mapping an anonymous function:

$ cat ... | fx '.map(x => x.author.name)'

or we can do the exact same thing with jq(1)-like syntax:

$ cat ... | fx .[].author.name
[
  "antonmedv",
  ...
]

note that [] can also be applied to map object values 👑

$ echo '{"foo": 1, "bar": 2}' | fx .[]
[1, 2]

💜 CHAINING

you can pass any number of anonymous functions for reducing the JSON:

$ echo '{"foo": [{"bar": "value"}]}' |
> fx 'x => x.foo' 'this[0]' 'this.bar'
value

💜 UPDATING

you can update existing JSON using the spread operator:

$ echo '{"count": 0}' | fx '{...this, count: 1}'
{
  "count": 1
}

💜 EDIT-IN-PLACE

fx provides a function save which will save everything in place and return the saved object. lowkey important: this function can only be used with a filename as the first argument to the fx command 🫶

usage:

$ fx data.json '{...this, count: this.count+1}' save .count

💜 USING PACKAGES

use any npm package by installing it globally:

$ npm install -g lodash
$ cat package.json |
> fx 'require("lodash").keys(this.dependencies)'

---

🌈 FORMATTING 🌈

if you need output other than JSON (for example, arguments for xargs), just don't return anything from the reducer. an undefined value is printed into stderr by default 👀

echo '[]' | fx 'void 0'
undefined

echo '[1,2,3]' |
  fx 'this.forEach(x => console.log(+x))' 2>/dev/null |
  xargs echo
1 2 3

---

⭐ STREAMING MODE ⭐

fx supports line-delimited JSON and concatenated JSON streaming 🦋

$ kubectl logs ... | fx .message

note that if an object lacks a message field, undefined will be printed to stderr. this is actually useful — it's how you see that you're skipping some objects. but if you want to hide them, just redirect stderr to /dev/null 💅

🎀 FILTERING

sometimes it's necessary to omit some messages in a JSON stream, or select only specified log messages. for this purpose, fx has special helpers select/filter — pass a function into it to select/filter JSON messages:

$ kubectl logs ... |
> fx 'select(x => x.status == 500)' .message

$ kubectl logs ... |
> fx 'filter(x => x.status < 499)' .message

and if filter/select are overridden in .fxrc, you're still able to access them with a prefix: std.select(cb) or std.filter(cd) 🫶

🌸 FILES 🌸

🗂️ USING .fxrc 🗂️

Okay bestie, first up: create .fxrc in your $HOME directory, and use it to require any packages or define global functions. It’s giving setup era ✨.

For example, you can access all the lodash methods without the _ prefix. Put this in your .fxrc file:

Object.assign(global, require('lodash/fp'))

And now you’ll be able to call all lodash methods. For example, see who’s been committing to react recently:

curl 'https://api.github.com/repos/facebook/react/commits?per_page=100' |
  fx 'groupBy("commit.author.name")' 'mapValues(size)' toPairs \
      'sortBy(1)' reverse 'take(10)' fromPairs

See the ENVIRONMENT section.

🔮 QUERY LANGUAGE 🔮

If you want to use a query language, for example jsonata, you can use a helper function like this:

global.jsonata = expr => require('jsonata')(expr).evaluate

And use it like this:

curl ... |
  fx 'jsonata("$sum(Order.Product.(Price * Quantity))")'

Instead, you can create this alias in your .bashrc file:

alias jsonata='FX_APPLY=jsonata fx'

And now all code arguments to jsonata will be passed through the jsonata helper. And now you can use it like this:

curl ... | jsonata '$sum(Order.Product.(Price * Quantity))'

🎮 INTERACTIVE MODE 🎮

Click on fields to expand or collapse the JSON tree, and use the mouse wheel to scroll the view 🖱️.

Here are the commands available in interactive mode:

• q or Esc or Ctrl+c — Exit
• up or k — Move cursor up
• left or h — Collapse
• right or l — Expand
• Shift+right or L — Expand all under cursor
• Shift+left or K — Collapse all under cursor
• e — Expand all
• E — Collapse all
• g — Scroll to top
• G — Scroll to bottom
• . — Edit filter
• / — Search
• n — Find next
• p — Exit and print JSON to stdout
• P — Exit and print fully expanded JSON to stdout

These commands are available when editing the filter:

• Enter — Apply filter
• Ctrl+u — Clear filter
• Ctrl+w — Delete last part
• up/down — Select autocomplete

🔍 SEARCHING 🔍

Press / and type a regexp pattern to search in the current JSON. Search works with the currently applied filter 👀.

Examples of a pattern and the corresponding regexp:

• Pattern /apple — RegExp /apple/ig
• Pattern /apple/+u — RegExp /apple/
• Pattern /apple/u+w — RegExp /apple/u
• Pattern \w+ — RegExp /\w+/ig

✂️ SELECTING TEXT ✂️

You might find that you literally can’t just select text in fx. That’s because all mouse events get redirected to stdin. To be able to select again, you need to tell your terminal not to do that. You can do it by holding special keys while selecting:

• Option+Mouse — iTerm2, Hyper
• Fn+Mouse — Terminal.app
• Shift+Mouse — Linux

Note: you can press p/P to print everything to stdout and select in there.

🧠 MEMORY USAGE 🧠

You may find that sometimes, on really big JSON files, fx prints an error message like this:

FATAL ERROR: JavaScript heap out of memory

V8 limits memory usage to around 2 GB by default. You can increase the limit by putting this line in your .profile:

export NODE_OPTIONS='--max-old-space-size=8192'

🌈 ENVIRONMENT 🌈

To be able to require global modules, make sure you have the correct NODE_PATH env variable.

💖 EXAMPLES 💖

✨ BASIC EXAMPLES ✨

$ echo '{"key": "value"}' | fx 'x => x.key'
value

$ echo '{"key": "value"}' | fx .key
value

$ echo '[1,2,3]' | fx 'this.map(x => x * 2)'
[2, 4, 6]

$ echo '{"items": ["one", "two"]}' | fx 'this.items' 'this[1]'
two

$ echo '{"count": 0}' | fx '{...this, count: 1}'
{"count": 1}

$ echo '{"foo": 1, "bar": 2}' | fx ?
["foo", "bar"]

🦋 OTHER EXAMPLES 🦋

Convert object to array:

$ cat package.json | fx 'Object.keys(this.dependencies)'

Or by two functions:

$ cat package.json | fx .dependencies Object.keys

By the way, fx has a shortcut for Object.keys. The previous example can be rewritten as:

$ cat package.json | fx .dependencies ?

👀 SEE ALSO 👀

• jq(1)

---

That’s the whole page, bestie! 🫶 The source/version is FX(1) and the date is February 2021 — iconic, no cap 💅✨.