twg 2.1.4

Terminal-based JSON & YAML viewer (TUI) for exploring and searching large files — fast, interactive, and privacy-first.

Twig 🌿

Inspect. Navigate. Understand.

A modern, terminal-based explorer for JSON and YAML files. Built for developers who work with real data in real environments.

What is Twig?

Twig is a high-performance terminal UI for exploring JSON and YAML files interactively. It turns deeply nested data into a navigable tree, letting you search, jump, and inspect complex structures without piping commands together or scrolling endlessly.

Twig is designed for understanding data, not editing it. It fills the gap between cat/less (no structure) and heavy IDEs (too slow/GUI-based), making it perfect for production logs, Kubernetes manifests, and large API responses.

---

Installation

Using uv (Recommended)

The modern, fast, and reliable way to install Python tools.

# 1. Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install Twig
uv tool install twg

Other Methods

Click to show pipx or pip instructions

Using pipx

pipx install twg

Using pip

Note: Recommended only for virtual environments.

pip install twg

Uninstalling

uv tool uninstall twg

---

Usage

Explore a file:

twg data.json
# or
twg config.yaml

Fix broken JSON: Automatically repair common errors (trailing commas, unquoted keys) or sanitize NaN/Infinity values:

twg --fix bad.json -o clean.json

Pretty Print:

twg -p large.json

Controls & Cheat Sheet

Key	Action	Key	Action
Navigation		Actions
Arrow Keys	Traverse Tree	c	Copy Path
/	Search (Global)	y	Copy Source
n / N	Next / Prev Match	t	Toggle Theme
:	Jump to path	?	Help
		q	Quit

---

Key Features

• 📂 Multi-Format: Native support for JSON and YAML.
• 👀 Read-Only by Design: Safely explore production data, logs, and configs without accidental edits.
• 🔍 Deep Search: Fast fuzzy search across keys and values (e.g. Pull matches imagePullPolicy).
• 🧭 Tree-Based Navigation: Navigate large, deeply nested files without losing context.
• 🎨 Themes: Includes Catppuccin Mocha (default) and Solarized Dark.
• ⚡ Performance-Focused: Designed to handle large files efficiently with a low memory footprint.

---

Why Twig Exists

Many real-world files — API responses, K8s manifests, Terraform state — contain sensitive information. Pasting them into web-based viewers is a security risk.

Existing CLI tools like jq are powerful for transformation but can be unintuitive for interactive exploration. Twig focuses purely on the latter:

• Runs entirely locally
• Works well over SSH and headless environments
• Optimized for reading, not mutation

Comparison

Tool	Strength	Limitation
jq	Powerful transformations	Steep learning curve for exploration
less / cat	Simple and universal	No structure awareness
Web viewers	Visual and easy	Privacy, size, and trust issues
Twig	Interactive understanding	Read-only, exploration-focused

Non-Goals

Twig is not:

• An editor.
• A replacement for jq.
• A streaming log viewer.

---

Performance & Architecture

Twig is built using Textual and uses SQLite with FTS5 for indexing. This allows instant search and navigation even for large files.

Benchmarks:

File Size	Load Time (Cold Start)	Experience
< 10MB	< 1s	⚡ Instant
50MB	~8s	🚀 Fast
90MB	~17s	✅ Usable
> 100MB	20s+	🐢 Slower

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for architecture details and setup instructions.

Star History