jq-repl

An interactive JSON explorer.

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

Warning

⚠️ This project is highly experimental, and until the 1.0 release, expect breaking changes that don't follow Semantic Versioning yet. Plans to support SemVer will be considered once this feels Stable™¹.

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 was learning jq (…I still am, but I was at the time too), and found the default repl cycle too slow, and wanted something more shortcut-friendly than https://jqplay.org. I discovered each of these tools over time (fzf, jq, vd, gron…) and thought "hey…", and the rest is history.

Why Rust?

Because I wanted to. 😁

I don't trust myself not to make a mistake in Bash, and I find it difficult to manage complex shell arguments and handle all the complex shell quoting³. Besides, I don't know Python. 🙂

Inspiration

• Implementing a jq REPL with fzf

Footnotes

1. Whatever that means. ↩

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

3. I'm sure there are a lot of bugs hiding in how stuff is quoted that I'm not aware of. If you find any, let me know! ↩