Tutorials on 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.

Tutorials on 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#