km8

README

km8 — KubeMate

A terminal UI for Kubernetes, inspired by Lens IDE, lazygit, lazydocker, and k9s. Built with Go and Bubble Tea.

Features

• 26 built-in resource types + CRD support -- dynamic discovery of Custom Resources at startup, across Cluster / Workloads / Network / Config / Storage / RBAC / Autoscaling categories
• Real-time Watch updates -- resources refresh automatically via Kubernetes Watch API
• Vim-style navigation -- j/k, u/d page scroll, gg/G, / search
• 3-panel lazygit-style layout -- numbered sidebar, list, and detail panels with scroll indicator
• Drill-down navigation -- Deployment / DaemonSet / StatefulSet / Job → Pods → Containers; CronJob → Jobs; HPA → target workload; PVC → mounting Pods; PDB → protected Pods
• Relatives tab — Lens-style graph navigation -- every detail panel (except Namespaces) lists the resource's navigable references (owners, selected pods, scaleTargetRef, mounted-by pods, ...). Enter/l drills into the cursor's ref — the panel re-renders showing that resource's Relatives, building a chain (Deployment → Pod → ConfigMap → consumer Pods, ...). h/Esc pops one level. b opens a breadcrumb popup so you can jump back to any ancestor in one step. Space jumps panels 1+2 to the cursor's ref (confirms first) — so a chain you walked into can become the new primary view. Tab label shows Relatives N at depth>1. Y opens the YAML of whichever entry the cursor is on. Cycle detection blocks revisiting an ancestor; fetch failures toast and stay put. 25 of 26 resource kinds covered — ConfigMaps / Secrets / ServiceAccounts surface reverse refs (which Pods use me, which RoleBindings name this SA as a subject, ...)
• YAML popup (Y) -- raw kubectl get -o yaml of the selected resource in a full-screen overlay with j/k/u/d/gg/G scroll, / search (n/N step through matches with full-row highlight), y to copy the full YAML to your clipboard, and e to dispatch kubectl edit directly from the popup. YAML lives in the popup, not the detail panel, so vertical layout no longer wraps long YAML lines awkwardly
• Pod log streaming with auto-follow -- multi-container support with <container>|<log> format; the Logs tab sticks to the tail by default (a ▼ marker in [3] Logs ▼ shows follow is active). Scroll up (k/↑/u/gg) to pause and read history; press G to catch up and resume following
• Aggregate logs for Deployments -- selecting a Deployment streams logs from every pod in the current ReplicaSet into a single Logs tab (also the default tab for Deployment detail). Lines are prefixed <pod-hash>│<container>│<text> with each segment in its own stable color, so during a rollout you can spot at a glance which pod is throwing errors without drill-down. Pods churning during rollout: the stream snapshots at row-select; re-select the Deployment row to refresh. Falls back to Deployment selector when current-ReplicaSet lookup fails (e.g. missing RBAC on ReplicaSet)
• Edit & shell exec via embedded PTY -- e runs kubectl edit and s runs kubectl exec -it -- /bin/sh, both inside an in-app virtual terminal so the editor and shell session never touch the host terminal scrollback. Editor honors $KUBE_EDITOR / $EDITOR (or config.yaml editor)
• KM8erm internal terminal -- Alt+t toggles an embedded shell (login shell with full env / cwd) inside km8 — like ssh localhost in a popup. Run kubectl apply -f, helm, anything you'd normally drop out of km8 to do. The shell is persistent: pressing Alt+t while the popup is visible hides it without killing the shell; pressing it again reattaches (cwd, history, env, background jobs all preserved). A green attached / amber km8erm chip in the status bar (right after ns:) shows which state you're in
• PTY scrollback -- 10k-line history for all PTY popups (KM8erm, shell exec, edit). PgUp / PgDn page, Home / End jump to top / live. Disabled in alt-screen apps (vim, less, htop) so they keep their own paging
• Colored Pod status -- Running green, Pending yellow, CrashLoopBackOff / ImagePullBackOff / OOMKilled red, Terminating gray. STATUS column shows the kubectl-equivalent reason, not raw Pod.Status.Phase
• Per-container colored log labels -- multi-container pods are visually distinguishable line-by-line; stable color per container name
• Resource deletion -- D with confirmation dialog
• Search/filter -- / to search in all three panels and in the namespace/context picker popups. Sidebar search also matches category names (e.g. "cluster" expands the Cluster category)
• Clipboard copy (y) -- copies the focused panel's content via OSC 52 (works through tmux/SSH, no xclip/pbcopy required). Inside the App Log popup (!), y copies the full log; inside the YAML popup, y copies the full YAML
• Toast notifications with levels -- info-level (1s sky-blue) for confirmations like "Copied!"; warning-level (2s peach with 󰀦) for blocked actions like Relatives cycle detection or drill failures
• Namespace and context switching -- n/N for namespace, c/C for context (uppercase aliases for users who prefer them; both open the same picker)
• Panel-aware selection styling -- the focused panel's cursor row gets a bright reverse-video highlight; the unfocused panel's selected row keeps a softer bg + bold so you can always see which resource each panel "remembers" while you work in another. Pod STATUS uses a darker palette variant when it lands on a light-bg highlighted row so the green/yellow/red stays readable
• Detail tabs -- Relatives / Logs (Pods + Deployments) / Events. Relatives is always first when present, so Space jumps land on the same tab you came from
• Long values wrap, never truncate -- applies to YAML, Events, and Logs; wrap points reflow on panel resize
• Panel expand -- =/- to toggle full-screen Table or Detail panel
• Theme system -- drop a theme.yaml into config directory to override colors
• Help & App Log overlays -- ? / ! popup on top of main UI
• Error notifications -- status bar badge + status line message
• Crash logging -- panics written to the km8 log directory
• Audit logging -- every kubectl edit and kubectl delete recorded to audit-*.log

Installation

Quick Install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/vulcanshen/km8/main/install.sh | sh

Quick Install (Windows PowerShell)

irm https://raw.githubusercontent.com/vulcanshen/km8/main/install.ps1 | iex

Homebrew (macOS/Linux)

brew install vulcanshen/tap/km8

Scoop (Windows)

scoop bucket add vulcanshen https://github.com/vulcanshen/scoop-bucket
scoop install km8

From source

go install github.com/vulcanshen/km8/cmd@latest

Uninstall

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/vulcanshen/km8/main/uninstall.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/vulcanshen/km8/main/uninstall.ps1 | iex

Build locally

git clone https://github.com/vulcanshen/km8.git
cd km8
go build -o km8 ./cmd/
./km8

Quick Start

km8

Connects to your current kubeconfig context. Use n to switch namespaces, c to switch contexts.

Key Bindings

Navigation

Key	Action
j / k	Move cursor up / down
u / d	Page up / down
gg / G	Jump to top / bottom
1 / 2 / 3	Switch panel
Tab	Cycle panels

Sidebar (Panel 1)

Key	Action
j / k	Move cursor (auto-selects the resource and restarts the watcher)
l / Enter	Move focus to Panel 2 (resource already selected by j/k, no reload)
/	Search / filter resource names + category names

Table (Panel 2)

Key	Action
/	Search / filter
Enter	Drill into children (Pods → Containers, HPA → workload, ...) or move focus to Panel 3 when the resource has nothing to drill into
e	Edit resource via kubectl edit (asks for confirmation)
D	Delete resource (asks for confirmation)
s	Shell into container via kubectl exec -it (asks for confirmation)

Detail (Panel 3)

Key	Action
h / l	Switch tab (only from Panel 2 — on Panel 3 these belong to the Relatives chain)
= / -	Expand / restore panel
G	Jump to bottom (on Logs: also resumes follow-tail)
k / ↑ / u / gg	Scroll up (on Logs: pauses follow-tail)

Relatives tab (drill chain)

Enter and l push a frame onto the chain; h / Esc pop. Space jumps the table to whatever ref the cursor is on (confirms first). The tab label shows depth as Relatives N once you've drilled, and the panel border carries a [b]readcrumbs hint at the top-right.

Key	Action
j / k	Move cursor between drillable refs
Enter / l	Drill into the cursor's ref (push frame)
h / Esc	Back one level (pop frame). No-op at root
b	Open the breadcrumb popup — j/k to pick a level, Enter to jump back, Space to switch panels to that level, Esc/q/b to close
Space	Switch panels 1+2 to the cursor's ref (asks for confirmation). Drill chain resets afterwards
Y	Open the YAML popup of the cursor's ref

Global

Key	Action
n / N	Switch namespace (/ to filter inside the popup)
c / C	Switch context (/ to filter inside the popup)
Alt+t	Toggle KM8erm (spawn / show / hide; shell stays alive across hide)
y	Copy focused panel content to clipboard (OSC 52)
Y	Open YAML popup (j/k/u/d/gg/G scroll, / search, y copy, e edit, Esc close)
!	App log
?	Toggle help
q	Quit km8 (asks for confirmation)
Ctrl+C	Quit km8 immediately (no confirm)
Esc	Close current modal / overlay

PTY popups (KM8erm, edit, shell exec)

Key	Action
PgUp / PgDn	Scroll history by one page
Home / End	Jump to top of history / back to live
Any other key	Snap back to live, key forwards to subprocess

Scrollback is disabled when a full-screen app (vim, less, htop) takes over the PTY via alt-screen; those keys forward to the app instead so it keeps its own paging.

Editing Resources

Pressing e on a resource runs kubectl edit <kind>/<name> -n <ns> --context <ctx> inside an embedded PTY popup. Behavior is identical to running the same command in a terminal: strategic merge patch, resourceVersion conflict detection, no last-applied-configuration annotation side-effect.

The editor is resolved by kubectl itself in this priority order:

1. $KUBE_EDITOR (km8 sets this if editor is configured in config.yaml)
2. $EDITOR
3. vi (Linux/macOS) or notepad (Windows)

When the editor exits, the popup closes and the table refreshes via the resource watch — no manual reload needed.

Why an embedded PTY?

Earlier versions of km8 ran the editor through tea.ExecProcess and applied the result with kubectl apply -f. That approach leaked kubectl's confirmation messages into the host terminal's scrollback after quitting km8, and the apply-vs-edit semantic mismatch surprised users coming from kubectl edit. The PTY popup keeps everything inside km8 and uses kubectl edit directly so behavior is exactly what kubectl edit users expect.

Note for nvim users

If your nvim setup has noticeable shutdown lag inside the popup (LSP attach/detach, plugin teardown), set editor: "nvim --noplugin" in config.yaml to skip plugin loading for the kubectl-edit session only. Your everyday nvim is unaffected.

Context Isolation

km8 maintains its own session-local context. Switching context with c inside km8 does not modify ~/.kube/config or the KUBECONFIG environment variable in any other terminal.

All kubectl subprocesses spawned by km8 (edit, delete, shell exec) receive an explicit --context <name> flag, so they always target the cluster km8 is showing — regardless of what kubectl's default context is set to.

This means you can safely run km8 in one terminal while using kubectl in another without either session interfering with the other's context.

Configuration

Config files are in the OS-appropriate config directory. Set XDG_CONFIG_HOME to override on any platform:

OS	Default Path
Linux	$XDG_CONFIG_HOME/km8/ or ~/.config/km8/
macOS	~/Library/Application Support/km8/
Windows	%APPDATA%/km8/

Logs (crash and audit) are written to the logs/ subdirectory of the config directory.

config.yaml

default_context: ""      # kubeconfig context (default: current-context)
default_namespace: ""    # namespace filter (default: all namespaces)
editor: ""               # exposed to kubectl as $KUBE_EDITOR
                         # (default: kubectl falls back to $EDITOR → vi / notepad)

theme.yaml

Drop a theme.yaml to customize colors. Only override what you need -- unspecified fields keep defaults.

sidebar:
  background: ""                       # empty = terminal transparent
  foreground: "#cdd6f4"
  selected_bg: "#bac2de"               # focused-panel cursor bg (reverse-video)
  selected_fg: "#1e1e2e"
  unfocused_selected_bg: "#353648"     # other-panel "remembered" selection bg
  unfocused_selected_fg: "#cdd6f4"
  category_fg: "#89b4fa"

table:
  header_bg: "#313244"
  header_fg: "#89b4fa"
  row_fg: "#cdd6f4"
  selected_row_bg: "#bac2de"           # focused-panel cursor bg (reverse-video)
  selected_row_fg: "#1e1e2e"
  unfocused_selected_row_bg: "#353648" # other-panel "remembered" selection bg
  unfocused_selected_row_fg: "#cdd6f4"
  alternating_bg: ""

detail:
  border_color: "#585b70"
  label_fg: "#89b4fa"
  value_fg: "#cdd6f4"
  tab_active_bg: "#45475a"
  tab_active_fg: "#cdd6f4"
  tab_inactive_fg: "#6c7086"

status_bar:
  background: "#181825"
  foreground: "#cdd6f4"
  cluster_fg: "#a6e3a1"
  namespace_fg: "#f9e2af"
  context_fg: "#89b4fa"

status_line:
  background: "#313244"
  foreground: "#a6adc8"

status:
  running: "#a6e3a1"
  pending: "#f9e2af"
  error: "#f38ba8"
  unknown: "#6c7086"

Requirements

• kubectl on $PATH (for edit, delete, and shell exec)
• A valid kubeconfig (~/.kube/config or $KUBECONFIG)
• A running Kubernetes cluster

License

GPL-3.0