kubectl-xctx

A kubectl plugin to execute commands across multiple Kubernetes contexts matching a regular expression.

Install via krew

kubectl krew index add be0x74a https://github.com/be0x74a/krew-index
kubectl krew install be0x74a/xctx

Or directly from the manifest:

kubectl krew install --manifest-url=https://raw.githubusercontent.com/be0x74a/krew-index/main/plugins/xctx.yaml

Usage

kubectl xctx [flags] <pattern> <kubectl args...>

xctx flags must come before the pattern. Everything after the pattern is passed directly to kubectl.

Flags

Flag	Short	Default	Description
--parallel	-p	false	Run across all contexts concurrently, buffering output per context
--stream		false	Run across all contexts concurrently, streaming live output prefixed with [context]
--list	-l	false	List matching contexts without executing
--timeout	-t	0	Per-context timeout (e.g. 10s, 1m). 0 = no timeout. With --stream, stops all streams after this duration
--fail-fast		false	Stop after first failure (sequential mode only)
--header		### Context: {context}	Header template. Use {context} as placeholder, "" to suppress
--version			Print version

Examples

# Get pods in all contexts matching "prod"
kubectl xctx "prod" get pods

# Get pods in a specific namespace
kubectl xctx "prod" get pods -n kube-system

# Get nodes across staging and dev contexts, in parallel
kubectl xctx --parallel "staging|dev" get nodes

# List which contexts would be selected
kubectl xctx --list "prod"

# Run with a per-context timeout (skip unreachable clusters)
kubectl xctx --timeout 10s "." get pods -n kube-system

# Follow logs across all matching contexts (streams live, prefixed per context)
kubectl xctx --stream "prod" logs -f -n my-ns -l app=my-app

# Watch pods across all matching contexts for 30 seconds
kubectl xctx --stream --timeout 30s "prod" get pods -w -n my-ns

# Stop immediately on first failure
kubectl xctx --fail-fast "prod" apply -f deployment.yaml

# Suppress headers (useful for piping)
kubectl xctx --header "" "prod" get pods -o json | jq .

Execution modes

• Sequential (default): one context at a time. Each context's output is written live, as it arrives, under its header.
• --parallel: all contexts concurrently. Output is buffered and printed grouped per context, in input order.
• --stream: all contexts concurrently, with stdout and stderr written live and each line prefixed with [context] (--header "" drops the prefix; output stays line-buffered so contexts never mix mid-line). Use it for commands that don't exit on their own, such as logs -f or get -w. --timeout stops all streams after the given duration. It can't be combined with --parallel or --fail-fast. Streams ended by Ctrl+C or --timeout are not reported as failures.

Output

Each context's output is grouped under a labeled header:

### Context: prod-us-east-1
NAME                    READY   STATUS    RESTARTS   AGE
my-app-abc123-xyz       1/1     Running   0          2d

### Context: prod-eu-west-1
NAME                    READY   STATUS    RESTARTS   AGE
my-app-def456-uvw       1/1     Running   0          2d

Shell completion

xctx supports tab completion for context names and kubectl commands. It uses kubectl's plugin completion protocol, which requires a kubectl_complete-xctx script on your PATH.

krew

printf '#!/usr/bin/env sh\nkubectl-xctx __complete "$@"\n' > ~/.krew/bin/kubectl_complete-xctx
chmod +x ~/.krew/bin/kubectl_complete-xctx

Homebrew / manual install

The kubectl_complete-xctx script is included in every release archive. Place it in the same directory as the kubectl-xctx binary (e.g. /usr/local/bin).

Build from source

make install          # installs both binary and completion script to /usr/local/bin
# or with a custom prefix:
make install PREFIX=~/.local/bin

Once installed, completions work out of the box in bash, zsh, and fish:

kubectl xctx <TAB>          # completes context names
kubectl xctx "prod" <TAB>   # completes kubectl subcommands (get, apply, ...)

Build from source

git clone https://github.com/be0x74a/kubectl-xctx
cd kubectl-xctx
go build -o kubectl-xctx .

License

MIT