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.

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. Extra flags pass through to kubectl (-n <namespace>, selectors, ...), and --match/-m filters rows by name substring. All-namespace listings (-A) are display-only — names aren't unique across namespaces.

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 and other resource types still use kx get <resource>.

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

Commands

Triage a namespace

Bare kx diag sweeps the current namespace — Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, Services, and PersistentVolumeClaims, 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.

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, 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 Docker Scout.

State

kx maintains a history of up to 10 kx get results in ~/.kx/state.json. A cursor tracks your current position; index-based commands always resolve against the entry at the cursor. kx state --all lists the history, kx state <position> jumps to an entry, kx back/kx forward step through it, and kx drop <position> removes one.

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

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run the CLI directly:

python -m kx.main --help

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