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 Python 3.11+ and kubectl on your PATH.

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 (no Python required; pending krew-index acceptance):

kubectl krew install kx
alias kx="kubectl kx"

Standalone binaries (linux/macOS, amd64/arm64, no Python required) are attached to each GitHub Release.

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

List resources

kx get <resource> [--match|-m <substring>] [kubectl flags...]

Fetches resources and assigns index numbers. Any extra flags (e.g. -n <namespace>, -A) are passed through to kubectl. Use --match/-m to filter results by name (substring, case-insensitive). All-namespace listings (-A) are display-only — rows aren't indexed, since names aren't unique across namespaces; scope to a namespace to select.

Known kinds can drop the get: kx pods, kx deploy -n kube-system, kx svc --match api. This covers the built-in kinds and their kubectl shorthands (po, deploy, svc, sts, ...); existing commands take precedence, so kx ns 3 still switches namespaces (bare kx ns lists them). CRDs and other resource types still use kx get <resource>. An integer after a kind is an index into the current state: kx po 3 (or kx get po 3) relists just that pod, erroring if index 3 isn't a pod. Multiple indexes work too: kx po 1 3.

$ kx get pods
Pods · default · 3 items
  X    NAME                      READY    STATUS     RESTARTS    AGE
  1    api-7d9f4b8c6-xkp2q       1/1      Running    0            2d
  2    worker-6c8b5f7d9-mnt4r    1/1      Running    3            5h
  3    postgres-0                1/1      Running    0           12d

All subsequent commands reference resources by their X index from the last kx get.

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

Commands

Example workflow

# list deployments, pick index 2
kx get deployments
kx describe 2

# check events on that deployment
kx events 2

# drill into a pod
kx get pods
kx logs 1
kx exec 1            # opens bash/sh
kx exec 1 -- env     # run a specific command

# forward local port 8080 to port 80 on a service
kx get services
kx port-forward 2 8080:80

# navigate history after multiple gets
kx get pods
kx get deployments
kx logs 1            # logs from pod index 1
kx state --all       # review full history

# clean up
kx delete 3

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 get pods          # saves a new entry, cursor advances
$ kx get deployments   # saves another entry, cursor advances
$ kx logs 1            # resolves index 1 from the pods result
$ kx state --all       # lists all history entries and the current position

Use kx state <position> to jump directly to any history entry, and kx drop <position> to remove 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        # list available themes (indexed) with a preview of each
kx theme nord   # persist a theme to ~/.kx/config.toml
kx theme 3      # same, selecting by index from the kx theme listing

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