kvx

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with kvx#

This tutorial walks you through installing kvx, loading your first data file, and exploring the output formats.

Installation#

Homebrew (macOS / Linux)#

brew install oakwood-commons/tap/kvx

Windows (winget)#

winget install OakwoodCommons.kvx

From Source#

go install github.com/oakwood-commons/kvx@latest

From Release Binaries#

Download the latest binary for your platform from GitHub Releases, extract it, and add it to your PATH.

macOS note: You may need to remove the quarantine attribute:

xattr -dr 'com.apple.quarantine' /usr/local/bin/kvx

First Run#

Create a sample file data.yaml:

Interactive Mode

Mon, 01 Jan 0001 00:00:00 +0000

Interactive Mode#

The interactive TUI lets you navigate, search, filter, and evaluate expressions against your data in a full-screen terminal interface.

Launching the TUI#

kvx data.yaml -i

Override terminal size detection:

kvx data.yaml -i --width 120 --height 40

Panels#

The TUI is organized into panels:

Data panel — Main table view. The bottom border shows the current CEL path (tail is kept when the path is long). The lower-right corner shows n/x for selection/visible rows.
Input panel — Single-line bordered input. Title reflects the current mode (Expression or Search). Hidden until activated.
Info panel — One row, borderless. Right-justified when input is hidden. Left-justified and recolored when input is shown.
Footer — Always visible. Left shows ? - Help, right shows rows/cols.
Help popup — Hidden by default. Press ? to toggle help content.

kvx defaults to vim keybindings:

CEL Expressions

Mon, 01 Jan 0001 00:00:00 +0000

CEL Expressions#

kvx uses the Common Expression Language (CEL) for dynamic querying, filtering, and transformation. This tutorial covers the expression syntax and common patterns.

Basics#

The root variable is always _. Use -e on the CLI or : in the TUI to evaluate expressions.

# Access a field
kvx data.yaml -e '_.metadata.name'

# Array index
kvx data.yaml -e '_.items[0]'

# Nested field access
kvx data.yaml -e '_.items[0].name'

Path Syntax#

kvx supports two path styles:

Configuration & Themes

Mon, 01 Jan 0001 00:00:00 +0000

Configuration & Themes#

This tutorial covers configuring kvx, selecting themes, using schema-driven column hints, and setting up shell completion.

Config File#

kvx merges built-in defaults with your config file at ~/.config/kvx/config.yaml (or $XDG_CONFIG_HOME/kvx/config.yaml). Override the config path with --config-file.

Viewing Configuration#

# Show merged config (defaults + your overrides)
kvx config get

# Output as JSON, YAML, or table
kvx config get -o json
kvx config get -o yaml
kvx config get -o table

# Interactive TUI view
kvx config get -i

# Print merged config without reading input
kvx --config

Using a Specific Config File#

kvx config get --config-file ~/.config/kvx/config.yaml
kvx data.yaml --config-file /path/to/custom-config.yaml

Themes#

Themes control the colors, borders, and styling of both TUI and CLI output.

TUI Quick Guide

Mon, 01 Jan 0001 00:00:00 +0000

TUI quick guide#

Launch & sizing#

Interactive: kvx <file> -i; one-shot renders use --snapshot (no -x alias). Add --press to script startup keys.
Size: --width/--height override terminal size; otherwise we detect and react to resizes.
No blank rows below the footer; panels scale proportionally when resizing.

Panels#

Footer: always visible; left shows ? - Help, right shows rows/cols.
Data panel: fills remaining space; bottom border shows current CEL path (tail is kept when long); lower-right of the data panel shows n/x for selection/visible rows (footer still shows rows/cols).
Input panel: one-line bordered; title reflects mode (Expression/Search); hidden by default.
Info panel: one row, borderless; right-justified when input is hidden, left-justified and recolored when input is shown.
Popup: hidden by default; ? toggles help content.

kvx defaults to vim keybinding mode:

Library Usage

Mon, 01 Jan 0001 00:00:00 +0000

Using kvx as a Library#

This guide covers everything you need to embed kvx in your own Go application — from a five-line quickstart to advanced customization.

Install#

go get github.com/oakwood-commons/kvx@latest

Quickstart#

There are two public packages. Pick the one that fits your use case:

Package	Import	Use when you want…
`pkg/core`	`github.com/oakwood-commons/kvx/pkg/core`	Load data, evaluate expressions, render plain text tables — no terminal UI
`pkg/tui`	`github.com/oakwood-commons/kvx/pkg/tui`	Launch the full interactive TUI or render bordered tables

Minimal example — render a table (no TUI)#

package main

import (
 "fmt"

 "github.com/oakwood-commons/kvx/pkg/core"
 "github.com/oakwood-commons/kvx/pkg/tui"
)

func main() {
 data := map[string]any{
 "name": "my-service",
 "version": "2.1.0",
 "healthy": true,
 }

 root, _ := core.LoadObject(data)

 // Bordered table, just like the kvx CLI
 fmt.Print(tui.RenderTable(root, tui.TableOptions{
 AppName: "my-app",
 Path: "_",
 Bordered: true,
 }))
}

Minimal example — launch the interactive TUI#

root, _ := core.LoadFile("data.yaml")

cfg := tui.DefaultConfig()
cfg.AppName = "my-app"

if err := tui.Run(root, cfg); err != nil {
 log.Fatal(err)
}

That’s it. Everything else below is optional.

Embedding the TUI

Mon, 01 Jan 0001 00:00:00 +0000

Embedding kvx in another app#

Use the public tui and core packages to run kvx inside your Go program. This guide covers data loading, configuration, and common extension points.

Data loading options#

Pick the loader that matches your source:

core.LoadFile(path) — read JSON/YAML/NDJSON from disk.
core.LoadRoot(input) / core.LoadRootBytes(data) — parse strings/bytes with format auto-detection.
core.LoadObject(value) — pass an already parsed Go value (map, slice, struct, etc.). Strings and byte slices are parsed through the same detection logic; nil inputs return an error.

Minimal embed#

package main

import (
 "log"

 "github.com/oakwood-commons/kvx/pkg/core"
 "github.com/oakwood-commons/kvx/pkg/tui"
)

func main() {
 // Use an existing Go value (no re-serialization needed)
 data := map[string]any{
 "service": "kvx",
 "owners": []any{"dev@acme.com", "ops@acme.com"},
 }

 root, err := core.LoadObject(data)
 if err != nil {
 log.Fatalf("load data: %v", err)
 }

 cfg := tui.DefaultConfig()

 if err := tui.Run(root, cfg); err != nil {
 log.Fatalf("tui error: %v", err)
 }
}

Swap core.LoadObject with core.LoadFile when you want to load from disk. For scripted renders (no interactive loop), use CLI-style flags with --snapshot via your own os.Args handling; the tui package itself always runs interactively.

Development

Mon, 01 Jan 0001 00:00:00 +0000

Development#

Prerequisites#

Go 1.20+
task (optional but recommended)

Building#

task build # recommended (builds to dist/kvx)
go build -o dist/kvx . # alternative (always use -o dist/kvx)

Note: The binary is built to dist/kvx, not the root directory. Always use -o dist/kvx when building manually.

Task Commands#

task build # Build binary
task run # Run with sample data
task run-interactive # Run TUI
task test # Run tests
go test ./... # Direct test execution

Testing#

Tests use fixture-based approach with deterministic Bubble Tea Update() calls:

kvx

Getting Started

Getting Started with kvx#

Installation#

Homebrew (macOS / Linux)#

Windows (winget)#

From Source#

From Release Binaries#

First Run#

Interactive Mode

Interactive Mode#

Launching the TUI#

Panels#

Navigation#

CEL Expressions

CEL Expressions#

Basics#

Path Syntax#

Configuration & Themes

Configuration & Themes#

Config File#

Viewing Configuration#

Using a Specific Config File#

Themes#

TUI Quick Guide

TUI quick guide#

Launch & sizing#

Panels#

Navigation basics#

Library Usage

Using kvx as a Library#

Install#

Quickstart#

Minimal example — render a table (no TUI)#

Minimal example — launch the interactive TUI#

Embedding the TUI

Embedding kvx in another app#

Data loading options#

Minimal embed#

Development

Development#

Prerequisites#

Building#

Task Commands#

Testing#