jq-repl

An interactive JSON explorer.

This is essentially a mix of shell tools that are useful for exploring JSON documents glued together to produce an interactive tool for transforming, viewing, and otherwise exploring JSON.

The gist of this program comes from this:

$ fzf --disabled --preview 'gojq {q} <file.json>'

That's the core of this program. Everything else is to make this process nicer: better file handling, dynamic shortcuts, default arguments, and so on.

Warning

This project is highly experimental, built to scratch an itch, so it might not be right for you. Consider this project unstable until the 1.0 release, as there may be breaking changes any time I feel like it. That being said, I've been using this tool for a number of years now, and it's been game-changing, so it might be worth trying out yourself.

See also: https://hannahilea.com/blog/houseplant-programming/

Usage

jq-repl ./foo.json
jq-repl <(jo -fruit=$(jo -a apple banana cherry))
cargo metadata --format-version=1 | jq-repl
jo foo=bar | jq-repl - ./baz.json

Double check you have the necessary binaries installed:

$ jq-repl --version-verbose
jq-repl x.y.z

fzf:	a.b (foobar)
gojq:	...
# ...

If you're ever are curious what it does behind-the-scenes, pass --show-fzf-command to give a rough Bash shell script of what it's actually constructing. Pass arguments to see how it changes.

This tool was built using the amazing work done by the tools it calls. Note that the defaults are highly opinionated, as this was built to scratch my own itch. There are flags you can pass to override the defaults. Here is a breakdown of some of the key programs called:

• fzf: The fast fuzzy-finder that provides the interface for this by abusing the --preview flag.

• jq/gojq/yq: The workhorse for processing query input. I typically use gojq, as it uses jq syntax exactly (unlike yq), and handles modules (I couldn't get them working with jq, ironically). If you want to use a different interpreter, pass it to --jq-bin. You may also want to pass --no-default-args, customize --color-flag and --no-color-flag, and pass any additional options as the last parameter. For example, if I were using yq, I could run it like this:

  cat mydoc.xml | jq-repl --jq-bin yq --no-default-args -- --input-format xml --output-format json

• vd (VisiData): A data explorer tool in the TUI. Bound to alt+v by default.

• bat: A pager with syntax highlighting. Bound by default to alt+L.

• less: A pager. Bound by default to alt+l.

• nvim (Neovim): A TUI editor based on Vim. Bound by default to alt+e. If you want to use a different editor, pass it to --editor (or set with $EDITOR), along with whatever options it you want with --editor-options. It needs to run in the foreground, and handle reading from standard input (/dev/stdin). For example, if you want to use Visual Studio Code, you can run this:

  jq-repl --editor code --editor-options '--wait -' ./path/to/file.json

• gron: Makes JSON greppable. Bound to ctrl+space by default. Toggle back with alt+space.

License

Released under MIT (see LICENSE). Note that any program called on by this is subject to its own license and terms¹.

Why?

I created this tool because I wanted to learn jq faster. I started with echo '{ "some": "json" }' | jq 'foo | map(bar)', but found that to be too slow for learning: I wanted to see the results of what I typed now, without having to scroll through the output or hit save in an editor. In my search for a good tool, I came across this Hacker News comment and decided to build around that myself.

Why Rust?

Because I wanted to. 😁

I don't trust myself to do this correctly in Bash, and I find it difficult to manage complex shell arguments and handle all the shell quoting. 🙂

Inspiration

• Implementing a jq REPL with fzf

Wait… isn't this a TUI, not a REPL?

Yeah, about that… to be honest, I didn't know the difference until much later. I feel like sticking with the current name, since it's muscle memory now, but for the pedantics out there, I appologize.

Footnotes

1. I am not a lawyer, so if I'm making a mistake here, please let me know! ↩