{"id":44887568,"url":"https://github.com/oakwood-commons/kvx","last_synced_at":"2026-04-27T20:00:46.372Z","repository":{"id":337813282,"uuid":"1154628636","full_name":"oakwood-commons/kvx","owner":"oakwood-commons","description":"A terminal-based UI for exploring structured data interactively","archived":false,"fork":false,"pushed_at":"2026-04-19T22:07:44.000Z","size":9847,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T00:20:07.895Z","etag":null,"topics":["cel","cli","csv","data-viewer","go","json","ndjson","terminal","toml","tui","yaml"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oakwood-commons.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T15:52:39.000Z","updated_at":"2026-04-19T22:06:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oakwood-commons/kvx","commit_stats":null,"previous_names":["oakwood-commons/kvx"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/oakwood-commons/kvx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oakwood-commons%2Fkvx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oakwood-commons%2Fkvx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oakwood-commons%2Fkvx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oakwood-commons%2Fkvx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oakwood-commons","download_url":"https://codeload.github.com/oakwood-commons/kvx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oakwood-commons%2Fkvx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32352406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T17:12:42.749Z","status":"ssl_error","status_checked_at":"2026-04-27T17:12:41.658Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cel","cli","csv","data-viewer","go","json","ndjson","terminal","toml","tui","yaml"],"created_at":"2026-02-17T18:05:39.303Z","updated_at":"2026-04-27T20:00:46.184Z","avatar_url":"https://github.com/oakwood-commons.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kvx\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/oakwood-commons/kvx)](https://goreportcard.com/report/github.com/oakwood-commons/kvx)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/oakwood-commons/kvx)](https://github.com/oakwood-commons/kvx/releases)\n[![CI](https://github.com/oakwood-commons/kvx/actions/workflows/ci.yml/badge.svg)](https://github.com/oakwood-commons/kvx/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/oakwood-commons/kvx/graph/badge.svg)](https://codecov.io/gh/oakwood-commons/kvx)\n[![Documentation](https://img.shields.io/badge/docs-oakwood--commons.github.io%2Fkvx-blue)](https://oakwood-commons.github.io/kvx/)\n\n\u003e **Alpha** — kvx is under active development. APIs and CLI flags may change between\n\u003e releases. Breaking changes are documented in release notes. Questions? Open an\n\u003e issue or start a [Discussion](https://github.com/oakwood-commons/kvx/discussions).\n\n**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.\n\n## Usage\n\n```bash\nkvx \u003cfile\u003e [flags]\nkvx tests/sample.yaml           # table output\nkvx tests/sample.yaml -i        # interactive TUI\n```\n\nSee [docs/development.md](docs/development.md) for build instructions and project setup.\n\n### Flags\n\n- `-i, --interactive` launch the TUI; `--snapshot` renders once and exits using the same layout as the TUI.\n- `--press \"\u003ckeys\u003e\"` script startup keys (e.g., `/name\u003cEnter\u003e`); include `\u003cF10\u003e` to bypass the TUI and emit non-interactive output (works regardless of `--keymap`).\n- `-e, --expression \u003ccel\u003e` evaluate CEL against `_` (e.g., `_.items[0].name`, `type(_)`); dotted shorthand stays TUI-only.\n- `--search \u003ctext\u003e` search keys/values; seeds search mode in TUI and prints a bordered table in non-interactive runs.\n- `-o, --output table|list|tree|yaml|json|toml|raw|csv` choose output format (default: `table`).\n- `--limit N`, `--offset N`, `--tail N` apply record limiting after any expression; `--tail` ignores `--offset` and cannot combine with `--limit`.\n- `--width N`, `--height N` override detected terminal size for TUI/snapshot/CLI bordered tables.\n- `--theme \u003cname\u003e` select a theme (default from config, falls back to `midnight`); `--no-color` disables colors and box drawing.\n- `--keymap vim|emacs|function` keybinding mode (default: `vim`); affects navigation keys in interactive mode.\n- `--schema \u003cpath\u003e` JSON Schema file for column display hints (title, maxLength, type, required, deprecated).\n- `--config-file \u003cpath\u003e` load config from a specific file; `--config` prints the merged config (defaults + XDG) in the chosen format.\n- `--sort ascending|descending|none` pick map key ordering; `--debug` enable debug logging and `--debug-max-events N` cap stored debug events.\n\n### Data formats and output\n\n- 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 `{}`.\n- 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.\n- 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: \u003cscalar\u003e`.\n- 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.\n- 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).\n- 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`).\n- 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.\n- YAML output defaults to indent `2` and literal block strings; these options are configurable via `formatting.yaml.*` in the config.\n\n## Config\n\nConfig 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.\n\nManage and inspect configuration via the `config` command group:\n\n```bash\n# Show merged config (defaults + XDG config)\nkvx config get\n\n# As JSON/YAML/Table\nkvx config get -o json\nkvx config get -o yaml\nkvx config get -o table\n\n# Interactive TUI view of the config\nkvx config get -i\n\n# Use an explicit config file instead of XDG\nkvx config get --config-file ~/.config/kvx/config.yaml\n```\n\n### Themes\n\n- Themes are defined in your config (`ui.themes`) and selected via `ui.theme.default` (default: `midnight`). Built-ins: `midnight`, `dark`, `warm`, `cool`.\n- List available themes from your merged config and see the default:\n\n```bash\nkvx config theme\n# or with an explicit file:\nkvx config theme --config-file ~/.config/kvx/config.yaml\n```\n\n- You can still pass a theme at runtime with `--theme \u003cname\u003e`; the default comes from your config.\n- `--no-color` removes colors and the box-drawing borders for parity with plain terminals.\n\n### Shell Completion\n\nGenerate shell completion scripts for bash, zsh, fish, or PowerShell:\n\n```bash\n# Bash (add to ~/.bashrc)\nkvx completion bash \u003e /etc/bash_completion.d/kvx\n\n# Zsh (add to ~/.zshrc)\nkvx completion zsh \u003e \"${fpath[1]}/_kvx\"\n\n# Fish\nkvx completion fish \u003e ~/.config/fish/completions/kvx.fish\n\n# PowerShell\nkvx completion powershell | Out-String | Invoke-Expression\n```\n\n### Shell Quoting\n\nWhen using expressions with special characters, prefer single quotes around the entire expression:\n\n- `'_.items[0]'`, `'type(_)'`, `'_.metadata[\"bad-key\"]'`\n- Double quotes require escaping internal quotes: `\"_.metadata[\\\"bad-key\\\"]\"`\n\n```bash\n# Print root as table\nkvx tests/sample.yaml\n\n# Navigate via CEL (CLI)\nkvx tests/sample.yaml -e '_.items[0].name'\n\n# Output as JSON\nkvx tests/sample.yaml -e '_.metadata' -o json\n\n# CEL functions\nkvx tests/sample.yaml -e 'type(_)'\n\n# Snapshot (render once) with scripted keys\nkvx tests/sample.yaml --snapshot --press \"\u003cRight\u003e\u003cRight\u003e\"\n\n# Non-interactive search\nkvx tests/sample.yaml --search status\n```\n\n### Path Syntax\n\n- CLI (strict CEL): use `_` as the root variable\n\t- `_.metadata.created`, `_.items[0]`, `type(_)`\n- TUI: dotted-path shorthand\n\t- `metadata.created`, `items[0]`, `items.0`, `items[0].name`\n\n### Limiting Records\n\n- `--limit N` shows the first N records after any `--expression` or filtering.\n- `--offset N` skips the first N records before applying `--limit`.\n- `--tail N` shows the last N records, ignores `--offset`, and cannot be combined with `--limit`.\n- Applies to arrays by index order and maps by stable sorted key order (same as CLI table rendering).\n- Non-interactive CLI output and snapshot TUI rendering use the same limiting rules; interactive scrolling does not change the applied limit.\n\n## Interactive Mode (TUI)\n\nkvx defaults to **vim** keybindings:\n\n| Key | Action |\n|-----|--------|\n| `j` / `k` | Navigate up/down |\n| `h` / `l` | Navigate back/forward (ascend/drill) |\n| `/` | Search mode (live search keys/values) |\n| `n` / `N` | Next/previous search match |\n| `f` | Filter current map keys |\n| `gg` / `G` | Go to top/bottom |\n| `:` | Expression mode (CEL) |\n| `y` | Copy current path/expression |\n| `?` | Toggle help panel |\n| `q` | Quit |\n| `Esc` | Close input/help/search context (does not quit) |\n\nPrefer **emacs** or **function-key** style bindings? Use `--keymap emacs` or `--keymap function`.\n\n**Panels:**\n- Data panel: main table view with path label and selection/total (`n/x`).\n- Help panel: overlay with navigation help (`?` to toggle).\n- Status bar: single-line info/error/status (right-aligned when input hidden).\n- Input panel: single-line bordered input (Expression/Search titles); hidden until activated.\n- Footer: bottom line with Help hint on the left and Rows/Cols on the right.\n\n**Filter \u0026 search:**\n- With input hidden, typing filters rows by key prefix; backspace edits; `Esc` clears; filter clears when you drill/ascend.\n- Search (`/`) keeps input open; results update live; `Right/Enter` drill, `Left` backs up within search base; `Esc` restores the prior node.\n\n**Expression (`:`):**\n- Starts with current path; Tab/Shift+Tab → keys/indices, Up/Down → CEL functions for the node type, Right accepts ghost completion.\n- `Enter` evaluates and stays in expr; errors in red; non-navigable results fall back to your prior path when you exit.\n\n## Embedding the TUI\n\nkvx's TUI can be embedded into your own Go application. See [docs/embedding.md](docs/embedding.md) for the full guide covering data loading, custom CEL functions, themes, and configuration. For a working example, see [`examples/embed-tui/`](examples/embed-tui/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foakwood-commons%2Fkvx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foakwood-commons%2Fkvx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foakwood-commons%2Fkvx/lists"}