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 method delivers the same prebuilt binary.

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

kubectl krew install idx
alias kx="kubectl idx"

Or from PyPI with uv — no Python runtime or dependencies required:

uv tool install kx-cli

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

pipx install kx-cli
pip install kx-cli

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

See the install guide for more.

Usage

No more copying names out of kubectl get — 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, either direction
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 — kx delete 3 --force --grace-period=0, kx logs 3 -f --tail=100. Passing -n with an index is refused, since the index already carries the namespace it was listed from.
• Listings made with -A are indexed too, each row with its own namespace.
• Known kinds drop the get — kx pods, kx deploy -n kube-system — kubectl's shorthands and your CRDs included.
• The --watch/-w flag redraws the table in place rather than appending lines.
• Tab completion, from kx completion <shell>, shows the resource behind each index: kx describe <TAB> offers 1 api-7d8f (Pod), not a bare number.

See the indexes guide for more.

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.

With an index, kx diag 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. See the triage guide for more.

Read a Secret in plaintext

The kx secret <index> --decode command prints an indexed Secret's keys and values decoded. With --key/-k, it 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. See the secrets guide for more.

Scan images for CVEs

The kx scan <index> command 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. See the scan guide for more.

See what owns what

The kx tree <index> command 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. See the ownership guide for more.

Reports in the browser

The --html flag 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.

Add --out <path> to write the page to a file instead of serving it — what you want in CI, where kx diag --out report.html is the whole command. See the browser reports guide for more.

Spend an index anywhere

Beyond the two dozen kubectl verbs kx wraps, the kx ref command 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

The --name, --namespace and --kind flags print one field alone, and nothing here touches the cluster, so kx ref answers instantly even with nothing reachable. See the kx ref guide for more.

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. Running kx state drop --all leaves marks alone; only kx unmark --all removes them. See the marks guide for more.

Use kx in CI

The --fail-on <severity> flag 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 healthy, 2 if not
kx scan -A --fail-on high                        # the same, for image CVEs
kx diag -A --fail-on critical --out report.html  # publish the report, then gate
kx diag -A --fail-on warning --since 24h         # ignore failures before today
kx scan --fail-on high --json | jq '.images[] | select(.counts.critical > 0)'

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". See the CI guide for more.

MCP server

The kx mcp command runs a Model Context Protocol server on stdio, so an agent — Claude Code, an IDE, an agent framework — reads a cluster the way you do: by kind and name, by a mark, or by an index from your current listing.

claude mcp add kx -- kx mcp

The MCP tools are read-only against the cluster; mark, the one write, only adds a name to kx's own state. Start it with --write-listings and the agent's listings join your history, tagged as the agent's, so you can spend its numbers yourself — and kx warns before a mutating command does.

claude mcp add kx -- kx mcp --write-listings

See the agent guide for more.

State and history

Recent kx get results are kept as a history — 10 by default, configurable — 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 the history; marks stay)
kx state drop --empty # drop the entries whose listing found nothing

Each entry remembers the context it was listed in, so a staging index is never resolved against production — kx refuses and relists instead. See the state guide for more.

Configuration

Settings live in ~/.kx/config.toml, and every one 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. See the configuration guide for more.

Themes

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

Eleven themes ship with it, github-dark by default. See the themes guide for more.

Commands

Every command takes indexes from the listing kx get last produced. The command reference covers every argument and flag.

Contributing

Building, testing and releasing kx are covered in CONTRIBUTING.md.

License

Released under the MIT License.