README
¶
kc
kc — kubernetes commander. A keyboard-driven, Midnight-Commander-style terminal UI for daily Kubernetes operations: browse the cluster, then deploy, restart, scale, tail logs, and exec — all from the keyboard, with learned defaults so the common path is a couple of keystrokes.
It's not another read-only dashboard: kc is built around doing things safely.
Mutations (deploy / restart / scale) are confirm-gated; logs and exec hand the
terminal to kubectl. See SPEC.md for the design.
Install
curl | sh (quickest — no prerequisites)
curl -fsSL https://raw.githubusercontent.com/backhand/kc/master/install.sh | sh
Grabs the prebuilt static binary for your OS/arch from the latest GitHub
release, verifies it against the release checksums.txt, and installs it to
/usr/local/bin. Override the destination with KC_INSTALL_DIR, or pin a
version with KC_VERSION (e.g. KC_VERSION=v0.1.0). No Homebrew tap-trust
needed.
Homebrew (macOS / Linux)
brew tap backhand/tap
brew trust --cask backhand/tap/kc # one-time, per machine (see below)
brew install kc
Homebrew 6.0+ won't evaluate a third-party tap's (unsandboxed) Ruby until you
explicitly trust it, so the one-time brew trust step is required before
install. Prefer trusting just the cask as above; to trust the whole tap
instead, run brew trust backhand/tap.
go install
go install github.com/backhand/kc@latest
Build from source
git clone https://github.com/backhand/kc && cd kc
make build # -> ./kc (static, no cgo)
Runtime requirements: kubectl (required — kc shells out to it for
everything), plus git + gh for the deploy flow (it lists GitHub releases to
pick a version). The Homebrew cask pulls in kubernetes-cli automatically.
Usage
kc # launch the TUI against your current kube-context
kc --version
kc --help
kc uses the ambient KUBECONFIG / current context (so OIDC/Dex auth via
kubectl works for free). Launched inside a git repo whose GHCR image runs on
the cluster, it opens straight at that app's namespace; elsewhere it opens at
all-namespaces. KC_NO_ALTSCREEN=1 kc renders a linear, pipeable stream.
Navigation — a zoom stack
all-namespaces → app-group → namespace → deployment → pods
Each level paints instantly from an on-disk cache and refreshes in the background, so it's never blocked on the apiserver.
| Key | Action |
|---|---|
↑/k ↓/j |
move the cursor |
enter / → |
drill in |
backspace/←/h |
zoom out |
/ |
search-everywhere (namespaces/deployments/pods) |
q / Ctrl+C |
quit |
? |
toggle help |
Operations (on the selected workload)
| Key | Operation | Notes |
|---|---|---|
d |
deploy | pick a release → kubectl set image; confirm-gated; learns presets |
r |
restart | kubectl rollout restart a set; confirm-gated |
s |
scale | scale a set to N replicas (0 = pause); confirm-gated |
l |
logs | stream kubectl logs -f for the selected deployment/pod |
e |
exec | open a shell (kubectl exec -it … -- sh) |
Deploy, restart, and scale share a set selection (checkboxes + learned
preset chips): the set containing the workload you're on is pre-checked, ←/→
cycle presets, number keys toggle them, and space toggles individual rows. The
pods list shows each pod's image version so you can watch a rollout flip live.
Development
make build # native static binary -> ./kc
make build-small # native, trimmed (-ldflags "-s -w")
make linux # Linux/amd64 static, one command
make test # headless render+input+exit smoke test (teatest)
- Go + the Charm stack (
bubbletea,lipgloss,bubbles). Go ≥ 1.25. - No cgo; the binary is a small (~3–5 MB) static executable that cross-compiles to Linux in one command.
- Everything Kubernetes/git/GitHub-shaped is a shell-out (
kubectl/git/gh) behind theinternal/packages;internal/tuiis the Bubble Tea app.
Releases are automated with GoReleaser — see RELEASING.md.
License
MIT © Frederik Hannibal
Documentation
¶
Overview ¶
Command kc is a keyboard-driven, Midnight-Commander-style CLI for daily Kubernetes operations. See SPEC.md for the design.
This entrypoint is deliberately thin: it resolves the runtime context (kube context for the cache key, repo context for the entry point), wires the data layer's caches + learning store into the TUI model, and runs the Bubble Tea program. All views / navigation / optimistic-render logic live in internal/tui; all Kubernetes/git/GitHub access lives in internal/*.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
cache
Package cache is the typed snapshot cache that makes kc startup feel instant.
|
Package cache is the typed snapshot cache that makes kc startup feel instant. |
|
deploy
Package deploy holds the mutating code in kc: the imperative `kubectl set image` that the confirm-gated deploy flow runs, the `kubectl rollout restart` the restart op runs, the `kubectl scale` the scale op runs, plus the `kubectl rollout status` they all watch afterwards (SPEC "Deploy flow (v1)" / "Operations").
|
Package deploy holds the mutating code in kc: the imperative `kubectl set image` that the confirm-gated deploy flow runs, the `kubectl rollout restart` the restart op runs, the `kubectl scale` the scale op runs, plus the `kubectl rollout status` they all watch afterwards (SPEC "Deploy flow (v1)" / "Operations"). |
|
exec
Package exec is the one place kc reaches the outside world.
|
Package exec is the one place kc reaches the outside world. |
|
git
Package git derives repo context from the cwd.
|
Package git derives repo context from the cwd. |
|
github
Package github wraps the `gh` CLI for the deploy flow's version list.
|
Package github wraps the `gh` CLI for the deploy flow's version list. |
|
k8s
Package k8s holds the kc data layer's Kubernetes domain types and the read-only kubectl wrappers + pure parsers that produce them.
|
Package k8s holds the kc data layer's Kubernetes domain types and the read-only kubectl wrappers + pure parsers that produce them. |
|
resolve
Package resolve maps a repo's GHCR image to the namespaces running it.
|
Package resolve maps a repo's GHCR image to the namespaces running it. |
|
store
Package store is the generic learning store (ActionHistory).
|
Package store is the generic learning store (ActionHistory). |
|
tui
Package tui is the kc Bubble Tea application: the one-stack zoom navigation over the read-only data layer, with optimistic render-from-cache + background refresh.
|
Package tui is the kc Bubble Tea application: the one-stack zoom navigation over the read-only data layer, with optimistic render-from-cache + background refresh. |