kcm — a TUI + CLI for managing local kubeconfig files and kubectl contexts, with tagging and destructive-action guardrails.
Full docs live in docs/ — start with Getting started.
- Browse kubeconfig files in a configurable directory (default
~/.kube). - Attach tags and alert policies to each kubeconfig — metadata is keyed by the file's SHA-256 so it survives renames and is ready for cloud sync.
- Destructive-action guard:
kcm kubectl delete|drain|cordon|...prompts for confirmation on flagged kubeconfigs. - Switch kubeconfigs with a shell-appropriate
export KUBECONFIG=...line (bash / zsh / pwsh). - Import, split, and merge kubeconfigs via
clientcmd— atomic writes, no half-written files. - Bubble Tea TUI with list, detail, tag editor, rename, and alert toggle.
Homebrew (macOS, Linux):
brew install loupeznik/tap/kcmArch (via AUR, pre-built binary):
yay -S kubeconfig-manager-bin # or paru, or any AUR helperSnap (any Linux distro with snapd). While kcm is on the v0.x line it ships on the edge channel; this flips to stable at v1.0.0.
sudo snap install kubeconfig-manager --classic --edgeDocker (multi-arch, cosign-signed):
docker pull ghcr.io/loupeznik/kubeconfig-manager:latestGitHub releases: pre-built tarballs for linux/darwin/windows on amd64 + arm64 live on the releases page.
From source (Go ≥ 1.26):
go install github.com/loupeznik/kubeconfig-manager/cmd/kubeconfig-manager@latestThe source install places the binary as kubeconfig-manager; symlink or alias to kcm for the shorter name. The brew, AUR, and Docker distributions already install it as kcm. The snap package ships both names (snap alias kubeconfig-manager kcm to activate the short name under strict snap alias rules).
kcm --help
kcm list
kcm use prod-eu
kcm tuiSee kcm <command> --help for per-command details.
kcm use and kcm tui print an export KUBECONFIG=... snippet to stdout (TUI rendering goes to stderr). To have the snippet actually update your current shell, you need a wrapper function — kcm install-shell-hook writes one for you.
kubeconfig-manager install-shell-hook # auto-detects your shell from $SHELL
kubeconfig-manager install-shell-hook --shell=zsh
kubeconfig-manager install-shell-hook --shell=pwshSupported first-class shells: bash, zsh, pwsh. The installer writes a fenced block into ~/.zshrc, ~/.bashrc, or the PowerShell profile (~/.config/powershell/Microsoft.PowerShell_profile.ps1 on unix, Documents/PowerShell/... on Windows). Reinstalling is idempotent — the block is replaced in place, not appended. Pass --rc <path> to target a custom file.
After install, restart your shell or source the rc file. Then:
kcm use prod-eu # updates KUBECONFIG in this shell
kcm tui # interactive picker; pressing `x` sets KUBECONFIGPass --alias-kubectl to additionally alias kubectl so every invocation routes through kcm kubectl, which enforces the per-kubeconfig destructive-action alerts:
kubeconfig-manager install-shell-hook --alias-kubectlTrade-offs: adds one process hop to every kubectl invocation, and alert confirmations intercept destructive commands (delete, drain, cordon, etc.) when the active kubeconfig has alerts enabled. Opt-in by design.
kubeconfig-manager uninstall-shell-hookRemoves the fenced block; the rest of your rc file is preserved. You can also edit the rc file manually — the block is clearly marked with # >>> kubeconfig-manager shell hook >>> / # <<< kubeconfig-manager shell hook <<< fences.
- User docs index
- Getting started
- Shell integration
- Destructive-action guard
- State file schema
- Architecture
- Roadmap (deferred features + docs-site framework recommendation)
CLI reference and man pages are regenerated from the command tree:
go run scripts/gendocs.goscripts/build.sh— builds./bin/kcmwith version info baked in.scripts/lint.sh— gofmt,go vet,golangci-lint.go test ./...— 66 unit tests across kubeconfig ops, state, shell, and guard packages.- Run the binary against
./.temp/rather than the real~/.kube/during development (seed mock kubeconfigs there; it's gitignored).