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 delivers the same prebuilt binary — no Python runtime, no dependencies.

With uv (recommended), pipx, or pip:

uv tool install kx-cli
pipx install kx-cli
pip install kx-cli

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

kubectl krew install idx
alias kx="kubectl idx"

Or run 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

Standalone binaries for linux, macOS and Windows are attached to every GitHub Release.

Full guide →

Usage

A kx session at a glance — one listing, then everything after it by number.

kx get pods    # lists pods, numbering each row
kx logs 3      # the third pod
kx diag 3      # why it's unhealthy

Indexes come several at a time, as ranges, or narrowed.

kx delete 3 5                   # several at once
kx delete 3..7                  # an inclusive range, walking either direction, trimmed to the listing
kx delete ..5                   # open at the start
kx delete 5..                   # open to the end of the listing
kx get pods -m api              # --match/-m filters rows by name substring
kx get pods -n prod -l app=api  # anything else passes through to kubectl

kubectl's own flags pass through everywhere they mean something — kx delete 3 --force --grace-period=0, kx rollout undo 3 --to-revision=2, kx scale 3 0 --timeout=1m, kx logs 3 -f --tail=100. A namespace flag is the exception: an index already carries the namespace it was listed from, so -n beside one is refused rather than silently retargeting the command.

-A listings are indexed too: each row records its own namespace, so kx describe 7 reaches a resource in a namespace you aren't in, and two pods sharing a name keep separate numbers.

Known kinds can drop the get — kx pods, kx deploy -n kube-system, kx svc -m api — kubectl's shorthands and your CRDs included. A CRD resolves from kubectl's on-disk discovery cache, with no API call.

--watch/-w redraws the table in place, rather than appending lines the way kubectl -w does.

kx completion <bash|zsh|fish|powershell> completes indexes with the resource behind them, so kx describe <TAB> offers 1 api-7d8f (Pod) rather than a bare number.

Triage a namespace

Bare kx diag sweeps the current namespace — every workload kind, plus Services, PVCs, Ingresses and pods nothing owns — and ranks what's unhealthy. It reads live usage too, so a pod running hot against its memory limit is flagged as an OOMKill risk before it dies.

kx diag <index> diagnoses a single resource: a top level verdict, a findings summary, a per-pod status table, log tails from broken containers and warning events — one screen instead of four kubectl commands.

Full guide →

Read a Secret in plaintext

kx secret <index> --decode prints an indexed Secret's keys and values decoded. --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)

Bare kx secret --decode decodes every Secret in the namespace in one call, confirming first — that prints every credential you have.

Full guide →

Scan images for CVEs

kx scan <index> scans the unique container images of an indexed workload. 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 and Grype via kx engine.

Full guide →

See what owns what

kx tree <index> walks the ownership graph — Deployment to ReplicaSet to Pods — and indexes every node it draws, so anything in the tree is one number away. Bare kx tree graphs the whole namespace.

Full guide →

Reports in the browser

--html on kx diag, kx scan, kx tree, and kx top renders the same analysis as a page and opens it in your browser. It binds 127.0.0.1 only and writes nothing to disk.

The page is drawn in your active theme. Sweep rows expand into that resource's full report, image rows into the CVEs behind their counts — detail the terminal has no room for.

--out <path> writes the page to a file instead of serving it, which is what you want in CI — kx diag --out report.html is the whole command.

Full guide →

Spend an index anywhere

kx wraps two dozen of kubectl's verbs. kx ref covers the rest, and every tool that isn't kubectl: it prints what an index refers to, as an argument fragment that drops straight into another command.

kx ref 3                                     # pod/web-abc-xyz -n prod
kubectl exec $(kx ref 3) -- sh               # a verb kx doesn't wrap
kubectl get $(kx ref 1..3)                   # one line each, so ranges work too
stern $(kx ref 3 --name) -n $(kx ref 3 --namespace)
kx ref 1..9 --name | xargs -n1 some-tool

--name, --namespace and --kind print that field alone, for tools that take the pieces separately. A cluster-scoped resource gets no -n, because there is no namespace for it to be in.

Nothing here touches the cluster: kx ref reports what the index means, so it answers instantly and works with nothing reachable. The command you spend it on is what discovers whether the resource is still there.

Marks

An index is a position, and positions move — the next kx get renumbers everything out from under it. A mark is a name you choose instead, pinned to one resource, so it keeps working across every listing that comes after it.

kx mark api 3          # pin what index 3 is right now
kx logs @api -f        # spend it where a command takes an index
kx exec @api -- sh
kx mark                # list marks
kx unmark api
kx unmark --all

A mark survives re-listing, which is what an index cannot do. It is pinned to the cluster it was taken in, and will not resolve in another — the same name means a different resource there, or none at all. kx state drop --all leaves marks alone; kx unmark --all is what removes them.

kx ns and kx context take an index but not a mark, because a slot is not a resource; kx cp parses its own index:path and takes one too.

Use kx in CI

--fail-on <severity> turns a sweep into a build gate, and --json prints the same analysis as a document for anything downstream.

kx diag -A --fail-on critical                        # 0 if the cluster is healthy, 2 if not
kx scan -A --fail-on high                            # the same, for image vulnerabilities
kx scan -n prod --fail-on high --json | jq '.images[] | select(.counts.critical > 0)'
kx diag -A --fail-on critical --out report.html      # publishes the report *and* fails the build
kx diag -A --fail-on warning --since 24h             # ignore what failed before today

--since bounds how far back the report looks — a warning event, an OOMKill a container recovered from, a pod or run that failed. Without it a failure from last month holds the gate red forever. Whatever is still going wrong — a CrashLoopBackOff, a Pending pod — is reported either way. Set the window once with diag_max_age in config.toml, or KX_DIAG_MAX_AGE in the job's environment.

kx events and kx logs take --since too. kx events has a key of its own, events_max_age / KX_EVENTS_MAX_AGE, and it does not affect kx diag — narrowing the evidence behind a verdict is not a request for a shorter event listing. Neither key falls back to the other.

Exit 2 means findings breached the threshold, 1 means kx itself failed — so a pipeline can tell "the cluster is sick" from "the check never ran".

Full guide →

State and history

kx keeps up to 10 kx get results in ~/.kx/state.json, with a cursor marking the entry indexes resolve against.

kx state              # the listing indexes currently resolve against
kx state --all        # the whole history, with positions
kx state 2            # jump to position 2
kx state back         # step back one (forward steps the other way)
kx state drop 2       # remove position 2 (--all clears everything, slots included, marks untouched)
kx state drop --empty # drop the entries whose listing found nothing

A listing that found nothing is saved like any other, so the indexes it replaced stop resolving rather than quietly pointing at the listing before it. kx offers the way back when it happens, and kx state drop --empty sweeps those entries up.

Each entry remembers the context it was listed in, so a staging index is never resolved against production — kx refuses and relists instead. KX_STATE points kx at a different state file, so a second terminal keeps its own history.

Full guide →

Configuration

kx reads ~/.kx/config.toml, and every setting takes a KX_* environment override. The two worth changing have commands of their own — kx theme and kx engine both persist your choice.

Styling is dropped when stdout isn't a terminal, so kx get pods | grep worker stays clean. NO_COLOR is honored too.

Full guide →

Themes

kx theme lists the available themes with a preview of each. kx theme <name> persists your choice, by name or index.

Eleven prefabs ship with it: github-dark (default), dracula, nord, gruvbox, solarized-dark, catppuccin-mocha, tokyo-night, rose-pine, mono, light and plain.

Full guide →

Commands

Development

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

go build ./...
go run ./cmd/kx --help              # run the CLI directly
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.

Releases are cut by pushing a release/vX.Y.Z branch — see RELEASING.md.