JSON & YAML Are Fine. Our Tools Aren’t.

#cli #devops #python #productivity

Does anyone else feel like they spend half their life just staring at 1,000-line YAML files, trying to figure out where a specific key actually lives?

I recently hit a wall while debugging complex workload definitions. You know the kind—where the structure of your JSON or YAML files actually determines the application logic.

Whether you are dealing with Kubernetes manifests or lengthy API responses, the nesting depth matters. A specific key located two spaces to the left might change a process from serial to parallel execution. I found that standard editors make it incredibly difficult to debug configuration drift when one wrong indentation level breaks the whole thing.

I realized I had three imperfect options:

VS Code: I’d collapse folders, expand others, scroll down, and suddenly lose track of which parent object I was actually looking at.
Online Formatters: These have two major problems. First, pasting sensitive production configs into a random web tool is a security nightmare. Second, browsers just can't handle the scale. Have you ever tried pasting a 50MB log file into a JSON formatter? It usually crashes the tab before it even renders the tree.
The CLI: cat and less are great for reading text, but they are awful for understanding structure.

I didn't want to write a query language just to look at my data, and I didn't want to wait for a browser to unfreeze. I just wanted to navigate my data like I navigate my files.

So, I built Twig.

What it actually does

Twig is a Terminal User Interface (TUI) that visualizes your data using Miller Columns.

If you use the "Columns" view in macOS Finder, you already get it. Instead of a vertical wall of text that pushes context off the screen, you drill down horizontally. You can see the parent, the child, and the value all at once.

Why I didn't just use `jq`

Trust me, I use jq every day. It’s the king of JSON processing for scripts and pipelines.

But using jq for exploration is painful. It’s a game of "Guess the Path." You run the command, see the output, tweak the path, run it again. It’s a Read-Eval-Print loop, not an interactive experience. Twig is for humans, not scripts. You don't need to know the path before you start; you discover it by walking through the tree.

I also tried tools like fx and jless. They are great, but they mostly rely on "folding" (like code folding). The problem I have with folding is that when you open a massive object, the parent key scrolls off the top of the screen. I constantly forgot "Wait, which ID does this block belong to?"

With Miller Columns, that parent context stays pinned in the left pane. It keeps your mental model intact.

The "Quality of Life" Stuff

Since I built this for my own sanity, I added a few features I needed for real work:

It fixes garbage data: We all get logs that aren't valid JSON—trailing commas, NaN values, or unquoted keys. Twig sanitizes common errors on the fly so you can view the file without having to manually fix it first.
Privacy first: Everything happens locally on your machine. No data leaves your terminal.
Fast search: You can fuzzy search for a key (like imagePullPolicy) and jump straight to it, no matter how deep it is in the hierarchy.

Try it out

It’s written in Python (using Textual), so it's easy to grab.

If you’re using uv (which makes Python tools way faster), you can run it instantly:

uv tool install twg

Or just standard pip:

pip install twg

Then point it at that massive file you've been dreading opening:

twg my-massive-log-file.json

Final Thoughts

The goal here isn't to replace your entire toolkit, but to fill that specific gap between "viewing raw text" and "writing complex queries."

We spend too much of our careers fighting with configuration files; our tools should make that easier, not harder. I’m building this in the open, and I’m actively looking for feedback to make it the best "quick-look" tool for the terminal.

If you give it a spin, let me know what you think in the comments or open an issue on the repo.