Documentation

Twig is a high-performance, terminal-based data explorer for JSON and YAML. It bridges the gap between simple text viewers (like less) and full-blown IDEs.

Designed for developers who work with large datasets, Kubernetes manifests, logs, or complex configuration files, Twig parses data into a navigable tree structure, allowing for rapid inspection without ever leaving the terminal.

Installation

The modern, fast, and reliable way to install Twig is using uv.

Using uv (Recommended)

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

# 2. Install Twig
uv tool install twg

Other Methods

Using pipx

pipx install twg

Using pip

Recommended only inside a virtual environment.

pip install twg

Core Workflow

Pass a data file to Twig. It automatically detects the format (JSON or YAML), indexes it, and launches the TUI.

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

CLI Reference

The twg command supports several flags for automation.

--fix

Attempts to automatically repair malformed JSON.

twg --fix broken.json

--print / -p

Pretty-prints the JSON/YAML file to stdout with syntax highlighting.

twg -p large.json

--version / -v

Display the current installed version.

Keyboard Shortcuts

Twig is designed for keyboard-centric workflows.

Configuration

Twig is zero-config by default. It automatically persists your settings between sessions.

• Theme: Twig supports multiple themes and saves your preference automatically. Cycles themes with the t key.
• Cache: Stored in ~/.twig/. Safe to delete at any time.

Troubleshooting

"Database Locked" Error

If Twig crashes or is killed forcefully, the SQLite lock file might remain. Run with --rebuild-db to reset.

Invalid JSON

If Twig refuses to open a file, run twg --fix file.json to see detailed error reports and attempt an automatic repair.

Community

Twig is open source. If you find it useful, please consider starring the project on GitHub to help others discover it.