kx is a kubectl wrapper that adds index-based resource selection. Run kx get <resource> once, then reference any result by number instead of typing full resource names.

Contents

• Install
• Usage
  • Commands
  • Triage a namespace
  • Read a Secret in plaintext
  • Scan images for vulnerabilities
  • View reports in a browser
• History
• Configuration
• Themes
• Development

Install

Requires kubectl on your PATH. Every install path below delivers the same prebuilt binary — no Python runtime, no dependencies.

With uv (recommended):

uv tool install kx-cli

With pipx:

pipx install kx-cli

With pip:

pip install kx-cli

As a kubectl plugin via krew, where kx is published as idx:

kubectl krew install idx
alias kx="kubectl idx"

Standalone binaries for linux, macOS and Windows (amd64/arm64) are attached to each GitHub Release, with checksums in SHA256SUMS.

On macOS, the first run of a freshly installed krew plugin or standalone binary takes a few seconds while Gatekeeper scans the binary; later runs are unaffected until the next install. Get it over with up front:

kx --version >/dev/null

Or try it without installing (the package is kx-cli, the command is kx):

uvx --from kx-cli kx get pods
pipx run --spec kx-cli kx get pods

Usage

kx get <resource> fetches resources and assigns each row an index; every other command takes those indexes. Several can be given at once (kx delete 3 5), and a run of consecutive ones can be written as a range instead of listing them out (kx delete 3..7, walking either direction); either end can be left open (kx delete ..5 from the start, kx delete 5.. to the end of the current listing). Extra flags pass through to kubectl (-n <namespace>, selectors, ...), and --match/-m filters rows by name substring. All-namespace listings (-A) are indexed like any other: each row records the namespace it came from, so kx describe 7 reaches a resource in a namespace you aren't in, and two pods sharing a name in different namespaces both keep their own number.

--watch redraws the table live as resources are added, changed, or removed, instead of printing a table that never finishes. It's display-only — a watch never completes, so there's nothing to index. Non-tabular output (-o json/yaml/etc.) streams kubectl's own watch output directly instead.

Known kinds can drop the get: kx pods, kx deploy -n kube-system, kx svc --match api — kubectl shorthands (po, deploy, svc, sts, ...) included. An integer after a kind relists just that index: kx po 3. CRDs work the same way — a CRD's own short name, kind, or plural — resolved from kubectl's own on-disk API-discovery cache, so kx never calls the API server just to look one up. A spelling that resolves neither way still falls back to kx get <resource>.

Global flags: --no-color disables styled output, -v/--version prints the installed version and how the binary was built, and -h/--help on any command shows usage, arguments, examples, and aliases.

kx completion <bash|zsh|fish|powershell> prints a completion script. It completes indexes from the saved listing with the resource each one points at, so kx describe <TAB> offers 1 api-7d8f (Pod) rather than a bare number — plus resource types, rollout actions, themes, engines, and namespaces for -n. Everything is answered from ~/.kx/state.json and needs no API call.

Commands

Triage a namespace

Bare kx diag sweeps the current namespace — Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, Services, PersistentVolumeClaims, and Ingresses, plus pods nothing owns — and prints a ranked table of what's unhealthy. Findings also draw on live resource usage (kx top): a pod running hot against its memory limit is flagged as an OOMKill risk before it dies. The rows are indexed, so kx diag 1 or kx logs 2 drill straight in. -A sweeps every namespace and indexes that too, adding a NAMESPACE column beside the numbers.

kx diag <index> diagnoses a single resource: a verdict banner, a SUMMARY of findings (CrashLoopBackOff, image pull failures, OOMKills, unschedulable pods, stalled rollouts, missing Service endpoints, Pending PVCs, failed CronJob runs, Ingresses referencing missing Services, usage near limits), a per-pod status table, recent log tails from broken containers, and warning events — one screen instead of four kubectl commands.

Read a Secret in plaintext

kx secret <index> --decode prints an indexed Secret's keys and values decoded, instead of the base64 kubectl returns. Values that aren't text show a <binary, N bytes> placeholder rather than garbling the table. --key/-k prints a single value raw — no banner, no wrapping — so it drops straight into a shell: export PGPASSWORD=$(kx secret 1 --decode -k password), or redirect a binary value to a file. Bare kx secret --decode decodes every Secret in the namespace in one call, -n included — it confirms first unless you pass --yes/-y, since that prints every credential in the namespace.

Scan images for vulnerabilities

kx scan <index> scans the unique container images of an indexed workload (init containers and CronJob job templates included); bare kx scan sweeps every workload in the namespace. Results come back as a severity summary, or the full per-image CVE report with --full. Requires the CLI for the selected engine — Docker Scout by default, or Trivy via kx engine trivy (see Configuration).

View reports in a browser

kx diag --html, kx scan --html, kx tree --html, and kx top --html render the same analysis as a page and open it in your browser as well as printing to the terminal; Ctrl-C stops the server. It binds 127.0.0.1 only, and nothing is written to disk — the report lives in memory for as long as the command runs.

The page is drawn in your active theme, so kx theme dracula restyles it too. Sweep rows expand into that resource's full report, and image rows expand into the CVEs behind their severity counts — detail the terminal has no room for. None of it costs an extra API or scanner call: both were already gathered to build the table you'd see without --html.

--port serves on a specific port instead of picking a free one, and --no-open skips launching a browser — the URL still prints, so you can open it yourself.

kx diag --html

A namespace sweep's severity-sorted findings, filterable and sortable by any column, with a group-by for larger sweeps.

kx scan --html

Per-image severity counts up top; the CVE table below groups by image and expands each row into its full detail.

kx tree --html

The ownership graph as a collapsible tree, indexed like every other kx listing.

History

kx maintains a history of up to 10 kx get results in ~/.kx/state.json. A cursor tracks your current position; index-based commands resolve against the entry at the cursor. kx state --all lists the history, kx state <position> jumps to an entry, kx state back/kx state forward step through it, and kx state drop <position> removes one (kx state drop --all clears everything, including the namespace/context slots below). The older kx back/kx forward/kx drop spellings still work too.

Each entry records the kubeconfig context it was listed in, since a resource name means nothing without the cluster it was read from. kx state names it beside the namespace; kx state --all captions the table with it, or gives it a column when the history spans more than one.

Switching contexts therefore retires the indexes you had. Rather than resolve them against the new cluster — where the same name is a different resource — kx refuses, names both contexts, and re-runs the listing here so there are usable numbers on screen: kx get pods in staging, kx context 2, then kx delete 1 deletes nothing and relists. kx ns <index> is refused the same way and tells you to run kx ns, since a namespace listing is per-cluster too. kx context <index> is the one exception — contexts live in kubeconfig rather than in any cluster, so switching back always works.

Namespaces and contexts are kept separately, outside that history. kx ns and kx contexts each save their listing to their own slot, so kx ns 2 counts against the namespaces you last listed no matter what you have listed since — and switching namespaces, which is frequent, never pushes work out of the history. kx state --all summarizes those slots under the history table, and kx state --targets expands them to the indexed listings the switch commands read, so you can pick a number without re-listing.

To operate on a namespace rather than switch to it, list it like any other resource with kx get ns; that puts it in the history too, so kx describe <index> and kx label <index> work as usual. It refreshes the slot as well, so the two spellings never disagree about what index 2 means. A narrowed listing counts, though: after kx get ns -l team=platform, kx ns <index> indexes into those namespaces rather than all of them. Run kx ns to list them all again.

Configuration

kx reads ~/.kx/config.toml; environment variables override file settings.

Styled output is emitted only when stdout is a terminal — piped or redirected output is plain text, so kx get pods | grep worker stays clean. The NO_COLOR convention is honored as well.

Themes

kx theme lists the available themes with a preview of each; kx theme <name|index> persists a choice to ~/.kx/config.toml.

Prefab themes: github-dark (default), dracula, nord, gruvbox, solarized-dark, catppuccin-mocha, tokyo-night, rose-pine, mono, light (for light terminal backgrounds), and plain (no styling at all).

Development

Go, at the version pinned by the go directive in go.mod. Nothing else is required to build or run.

go build ./...

Run the CLI directly:

go run ./cmd/kx --help
go run ./cmd/kx get pods

Checks:

gofmt -l ./cmd ./internal ./tools   # must print nothing
go vet ./...
go test -race ./...

pre-commit run --all-files runs gofmt and go vet, and regenerates the command table above from the command tree — it fails if the table has drifted from the commands it documents. Tests are not in the hook; run them yourself.

The demo GIFs are rendered from VHS tapes — see demo/README.md for seeding the demo namespace and re-recording.