kvx is a terminal-based UI tool designed for exploring structured data formats such as JSON, YAML, TOML, CSV, and JWT in an interactive and navigable way. It allows users to view and manipulate data as key-value trees, making it easier to understand complex or deeply nested structures directly within the terminal.
Key Features:
Interactive TUI with support for Vim and Emacs keybindings.
Evaluate CEL (Common Expression Language) expressions to extract specific values.
Multiple output formats including table, list, tree, YAML, JSON, TOML, raw, CSV, Mermaid flowchart syntax, and more.
Search capabilities to find keys or values within the data.
Configurable themes for different visual preferences.
Audience & Benefit:
Ideal for developers, data analysts, DevOps engineers, and anyone working with structured data who need a fast and efficient way to explore and understand complex datasets. kvx helps users quickly navigate through nested structures, evaluate specific data points using CEL expressions, and customize the output format or theme to suit their workflow.
kvx can be installed via winget for easy setup on Windows systems.
README
kvx
> Alpha — kvx is under active development. APIs and CLI flags may change between
> releases. Breaking changes are documented in release notes. Questions? Open an
> issue or start a Discussion.
kvx is a terminal-based UI for exploring structured data like JSON, YAML, and TOML in an interactive, navigable way. It presents data as key value trees that you can expand, collapse, and inspect directly in the terminal, making it easy to understand complex or deeply nested structures. In addition to being a standalone CLI, kvx is designed as a reusable TUI component, allowing other applications to embed the viewer directly into their own terminal interfaces for consistent data inspection and visualization.
--config-file load config from a specific file; --config prints the merged config (defaults + XDG) in the chosen format.
--sort ascending|descending|none pick map key ordering; --debug enable debug logging and --debug-max-events N cap stored debug events.
Data formats and output
Input auto-detects YAML/JSON (single or multi-doc), NDJSON, TOML (by extension or content), and CSV (by extension or stdin shape). If no input is provided, kvx shows help; with --expression but no input, it evaluates against an empty object {}.
Non-interactive table output renders a bordered table with header/footer parity to the TUI; scalars print raw, and simple scalar arrays print one value per line.
List output (-o list) displays data in a vertical format with each property on its own line. Arrays of objects show each element with an index header ([0], [1], etc.) and indented properties beneath. Maps display as key: value pairs, and scalars show as value: .
Tree output (-o tree) renders data as an ASCII tree structure using box-drawing characters. Nested objects become branches, arrays show indexed children, and scalar values appear inline. Options: --tree-depth N limits depth, --tree-no-values shows structure only, --tree-expand-arrays expands all array elements.
Mermaid output (-o mermaid) generates Mermaid flowchart syntax for visualization in Markdown or diagram tools. Use --mermaid-direction TD|LR|BT|RL to set flow direction (default: TD for top-down).
Array index style: --array-style index|numbered|bullet|none controls how array elements are labeled. Default is index ([0], [1]); use numbered for 1, 2, bullet for •, or none to hide indices (useful with -o list).
CSV output is available for CLI/snapshot runs: arrays of objects become rows with merged headers, maps become key/value rows, other values emit a single value column.
YAML output defaults to indent 2 and literal block strings; these options are configurable via formatting.yaml.* in the config.
Config
Config merges built-in defaults with ~/.config/kvx/config.yaml (or XDG_CONFIG_HOME/kvx/config.yaml); override with --config-file. Use kvx --config to print the merged view without reading input.
Manage and inspect configuration via the config command group:
# Show merged config (defaults + XDG config)
kvx config get
# As JSON/YAML/Table
kvx config get -o json
kvx config get -o yaml
kvx config get -o table
# Interactive TUI view of the config
kvx config get -i
# Use an explicit config file instead of XDG
kvx config get --config-file ~/.config/kvx/config.yaml
Themes
Themes are defined in your config (ui.themes) and selected via ui.theme.default (default: midnight). Built-ins: midnight, dark, warm, cool.
List available themes from your merged config and see the default:
kvx config theme
# or with an explicit file:
kvx config theme --config-file ~/.config/kvx/config.yaml
You can still pass a theme at runtime with --theme ; the default comes from your config.
--no-color removes colors and the box-drawing borders for parity with plain terminals.
Shell Completion
Generate shell completion scripts for bash, zsh, fish, or PowerShell:
# Bash (add to ~/.bashrc)
kvx completion bash > /etc/bash_completion.d/kvx
# Zsh (add to ~/.zshrc)
kvx completion zsh > "${fpath[1]}/_kvx"
# Fish
kvx completion fish > ~/.config/fish/completions/kvx.fish
# PowerShell
kvx completion powershell | Out-String | Invoke-Expression
Shell Quoting
When using expressions with special characters, prefer single quotes around the entire expression:
--limit N shows the first N records after any --expression or filtering.
--offset N skips the first N records before applying --limit.
--tail N shows the last N records, ignores --offset, and cannot be combined with --limit.
Applies to arrays by index order and maps by stable sorted key order (same as CLI table rendering).
Non-interactive CLI output and snapshot TUI rendering use the same limiting rules; interactive scrolling does not change the applied limit.
Interactive Mode (TUI)
kvx defaults to vim keybindings:
Key
Action
j / k
Navigate up/down
h / l
Navigate back/forward (ascend/drill)
/
Search mode (live search keys/values)
n / N
Next/previous search match
f
Filter current map keys
gg / G
Go to top/bottom
:
Expression mode (CEL)
y
Copy current path/expression
?
Toggle help panel
q
Quit
Esc
Close input/help/search context (does not quit)
Prefer emacs or function-key style bindings? Use --keymap emacs or --keymap function.
Panels:
Data panel: main table view with path label and selection/total (n/x).
Help panel: overlay with navigation help (? to toggle).
Status bar: single-line info/error/status (right-aligned when input hidden).
Input panel: single-line bordered input (Expression/Search titles); hidden until activated.
Footer: bottom line with Help hint on the left and Rows/Cols on the right.
Filter & search:
With input hidden, typing filters rows by key prefix; backspace edits; Esc clears; filter clears when you drill/ascend.
Search (/) keeps input open; results update live; Right/Enter drill, Left backs up within search base; Esc restores the prior node.
Expression (:):
Starts with current path; Tab/Shift+Tab → keys/indices, Up/Down → CEL functions for the node type, Right accepts ghost completion.
Enter evaluates and stays in expr; errors in red; non-navigable results fall back to your prior path when you exit.
Embedding the TUI
kvx's TUI can be embedded into your own Go application. See docs/embedding.md for the full guide covering data loading, custom CEL functions, themes, and configuration. For a working example, see examples/embed-tui/.
