Single

JSONQuill, A Structured Editor for JSON

Posted
By Joey Gibson
4 min read
JSONQuill, A Structured Editor for JSON

I spend a lot of my day staring at JSON. API responses, config files, log dumps… it’s JSON all day. And for years my workflow has been some combination of jq, piping stuff into less, or just opening files in vim and hoping for the best. The problem is that, with the exception of jq, none of those tools actually understand JSON. Vim doesn’t care if you delete a comma and break the whole file. jq is great for reading, but it’s not an editor. And less is less. I wanted something that would let me navigate and edit JSON in a structured way, as a tree of keys and values, while keeping me from accidentally producing garbage.

So I built JSONQuill, a terminal-based structured editor for JSON with vim-style keybindings. It’s written in Rust, it’s MIT licensed, and it runs on macOS (Apple Silicon and Intel), Linux, and Windows.

The cool thing is that JSONQuill doesn’t treat your file as text. It parses the JSON into a tree and lets you navigate, expand, collapse, search, and edit nodes directly. It tries very hard to keep you from creating invalid JSON, and if something does go wrong internally, it re-validates the entire document before writing to disk, so it won’t silently corrupt your files.

I was inspired by jless, which is a fantastic JSON viewer. But I kept wanting to tweak values, add keys, delete nodes, etc.; you know, actually edit things. JSONQuill fills that gap.

Here’s a quick demo showing navigation, searching, and editing a JSON file:

What it can do

There are a lot of features, but here are the highlights:

  • Real vim keybindings. Not just hjkl. Count prefixes (3j to move down 3 lines), marks (ma to set, 'a to jump back), a jump list, visual mode for bulk operations, named registers, yank/delete with yy/dd, undo/redo, and the . repeat command. If your fingers know vim, they already know JSONQuill. And there’s a full in-app help screen, available by pressing <F1>.

  • Pipe from stdin. I use this a lot. Grab an API response and immediately start exploring it:

    class="highlight">
    1

    curl -s https://api.example.com/config | jsonquill

  • Search. Hit / to search forward (or ? for backward) across both keys and values. It supports smart case (case-insensitive until you type a capital letter) and JSONPath structural search for when you need to find something deep in a nested mess.

  • JSONL support. If you work with JSON Lines files (.jsonl or .ndjson), JSONQuill handles them natively. Each line shows a collapsed preview, and you can expand any line to drill into it.

  • Gzip-compressed files. Editing, and saving, (.json.gz, .jsonl.gz) work transparently; just open them directly.

  • JQ-style formatter. If you type :format your document will get reformatted just like jq would.

  • Format preservation. If you open a file, edit one value, and save it, only the node you touched gets formatted. Everything else keeps its exact original whitespace and indentation. No more phantom diffs in your git history because your editor decided to reformat the entire file.

  • Data safety. Every save re-parses the generated JSON to verify it’s valid before writing. Writes are atomic (temp file, then rename) so your original is never left in a partial state. You can also enable automatic .bak file creation in the config if you’re the belt-and-suspenders type.

    A quick workflow

    Say you’ve got a big JSON config file and you need to find and update a value:

    1. jsonquill config.json to open the file as a collapsible tree
    2. j/k to move up and down, l to expand a node, h to collapse it (arrow keys, work, too)
    3. /database to search for the key you’re looking for
    4. e to edit the value at the cursor, which puts you in edit mode
    5. Make your change, hit Enter to return to normal mode
    6. :w to save, :q to quit (or :wq because of course)

    It should all feel very familiar if you use vim, though there are a few differences. i inserts a key/value pair. a inserts an array. o inserts an object.

    Installation

    On macOS, the easiest way is Homebrew:

    class="highlight">
    1
2
3
4
5

    # Add the tap
brew tap joeygibson/tools

# Install jsonquill
brew install jsonquill

    On Linux and Windows, grab a zip file from the latest release.

    Or build from source if you’ve got a Rust toolchain handy:

    class="highlight">
    1
2
3
4

    git clone https://github.com/joeygibson/jsonquill
cd jsonquill
cargo build --release
./target/release/jsonquill examples/sample.json

    What’s next

    I’ve been using JSONQuill pretty much every day and I’m really enjoying it. It’s just a few months old, but it’s solid and stable for daily use right now.

    If you spend any amount of time working with JSON in a terminal, give it a try. And if you have feedback, find a bug, or want to contribute, here’s the repo. Let me know what you think.

    apps
    json tool editor rust terminal
    This post is licensed under CC BY 4.0 by the author.