GET STARTED

First installation and trial

KubeRich 0.1.0 has live pods, namespace/context tables, inline command completion, local filters, 15 standard resource tables, resource details/YAML/events, generic CRD tables, single/aggregate logs and embedded container shells. Public PyPI, Homebrew and standalone installations are available. See installation and upgrades for channels and measured scope. Guarded annotations, manifest editing, workload scale/restart/rollback and managed pod/Service port forwarding, guarded deletion and Job operations are also available. Exec credentials, certificates and proxies have locally verified connection contracts; see connection compatibility. Captured attach and file transfer are delivered; metrics, creating ephemeral debug containers and user plugins are planned. Embedded-shell history/search/copy is delivered: Alt+PageUp opens local review, / searches, v selects, y copies with recognized credential redaction and Enter/Escape returns to live output. This preview does not claim complete K9s parity or real EKS/AKS certification.

Install the public release

On Linux or macOS, choose one method:

brew install kuberich/tap/kuberich
# Alternative with Python 3.12–3.14:
uv tool install --python 3.12 kuberich

Then run kuberich --version, kuberich config check and kuberich --context YOUR_CONTEXT --namespace YOUR_NAMESPACE --readonly. Use your intended context and namespace. The remaining examples use a source checkout; omit uv run when using the installed command.

Run from source

Use Linux or macOS, Python 3.12–3.14 and uv. In a trusted source checkout:

git switch main
git pull --ff-only
uv sync --locked --group dev --python 3.12
uv run kuberich --version
uv run kuberich --help
uv run kuberich config check
uv run kuberich info

Version/help/config/info need no cluster. The UI needs an interactive terminal; redirecting its input/output is not a way to launch it. --config selects KubeRich preferences; --kubeconfig selects Kubernetes credentials/configuration.

Choose an explicitly permitted context/namespace. To list local context names:

kubectl config get-contexts -o name
uv run kuberich --context YOUR_CONTEXT --namespace YOUR_NAMESPACE --readonly

For a separate trusted kubeconfig, use its absolute path consistently:

kubectl --kubeconfig /absolute/path/to/kubeconfig config get-contexts -o name
uv run kuberich --kubeconfig /absolute/path/to/kubeconfig --context YOUR_CONTEXT --namespace YOUR_NAMESPACE --readonly

Replace the uppercase names. No kubectl config use-context is required. KubeRich preserves the source kubeconfig and captures each connection separately. --readonly blocks shells and effectful commands; the server still decides which reads your identity may perform.

Try the interface in order

1. Confirm the context/namespace and version in the header, and that real pods appear. Empty, denied, connecting and disconnected are distinct states.
2. Type :ctx, Enter. Contexts form a table. Use arrows and Enter to connect. :ctx EXACT_NAME connects directly; Escape restores the prior view.
3. Type :ns, Enter. Filter with /, type a namespace, Enter to return to its table, then Enter on the selected row to open pods. :ns EXACT_NAME selects it directly; :ns * selects all namespaces.
4. On pods, / starts a local filter. Type text and Enter; Escape in the table clears it. re:api|worker is the explicit regex form. Resize the terminal and use arrows/PageUp/PageDown to browse. s sorts pods; Shift+S reverses order.
5. Select a pod: d opens details, y YAML and e its events. Escape returns. Inspection hides sensitive field sets by default; it is not an editor.
6. Enter on a pod opens its container table. Enter on a container opens that container's logs. In logs, p pauses, f follows, g/G goes first/last, / searches, n/N moves through matches, t toggles timestamps and w wraps. Escape returns to containers; another Escape returns to pods.
7. In the : bar, type c and use Tab to accept the inline suggestion. Up/Down cycles candidates. :back / :forward restores navigation history; ? shows the actual actions for the current view.
8. Ctrl+Q quits and restores the terminal. q also quits outside inputs/shells.

See commands, workspace, inspection and logs for full controls.

Try a shell in your test namespace

Install kubectl on PATH with a version supported by the cluster. The account needs pod reads and pods/exec; the chosen image must contain sh or your configured shell. Exit the read-only preview, then deliberately enable shell actions for this invocation:

uv run kuberich --kubeconfig /absolute/path/to/test-kubeconfig --context YOUR_TEST_CONTEXT --namespace YOUR_TEST_NAMESPACE --write

--write overrides a read-only preference without changing its file. Select the pod, Enter, select the container and press s or x. The shell occupies the embedded Textual terminal, with its captured context/pod/container shown above. It uses kubectl exec, not SSH into the pod or node.

Inside it, pwd or printf 'hello\n' are enough for a basic trial. exit or Ctrl+D returns to containers; Ctrl+] closes the owned session locally. Ctrl+C interrupts the remote program; Ctrl+Q quits KubeRich. Escape, Tab, arrows, :, / and q are delivered to the remote program while the shell is open. After returning, Escape goes back to pods. Distroless/completed containers or an image without a shell need a suitable image; ephemeral debugging is not available yet. Shell requirements and limits.

EKS and AKS prerequisites

Use the same trusted kubeconfig, user, helper PATH and provider login that work with explicit-context kubectl. KubeRich invokes the declared exec helper; it does not provision clusters or manage a separate credential database.

• EKS: AWS CLI with the configured profile/role/session. If the profile uses SSO, run aws sso login --profile YOUR_PROFILE externally, then :retry.
• AKS: Azure kubelogin for its declared login mode; azurecli additionally needs Azure CLI and the intended az login session. An Azure helper requiring interaction can use the explicit :login action; it runs the declared helper. KubeRich does not infer a different tenant/login mode or convert the kubeconfig.

The local adapter/process contracts are verified with owned helpers and kind. Actual AWS/EKS and Microsoft Entra/AKS certification needs separate provider trials. Read EKS and AKS for supported versions/modes, refresh behavior and certification limits.

Install a supplied local candidate

For a trusted wheel supplied by the maintainer, run outside the checkout:

uv tool install --python 3.12 /absolute/path/to/kuberich-VERSION-py3-none-any.whl
kuberich --version
kuberich --help
kuberich config check
kuberich info
kuberich --kubeconfig /absolute/path/to/kubeconfig --context YOUR_CONTEXT --namespace YOUR_NAMESPACE --readonly

Use the actual filename/version. If uv reports its tool bin directory missing from PATH, add the directory it reports using your preferred shell setup. The rehearsal uses private tool directories and an absolute executable path; it never changes your shell configuration or existing tool installation. pipx install --python python3.12 /absolute/path/to/WHEEL.whl is the alternative already qualified by packaging checks. Do not install the same CLI with both.

Uninstall with uv tool uninstall kuberich or, for pipx, pipx uninstall kuberich. Preferences/logs remain separate from the installed application. Running through the checkout does not create a uv tool installation to uninstall.

PyPI and the public Homebrew tap are available first-release channels. First 0.1.0 uses an identified local upgrade baseline, without inventing a previous public version; later trials use the actual published predecessor. See upgrade constraints. Four qualified standalone Linux/macOS archives are available in the 0.1.0 release.

If something fails

For feedback, give the version, OS/terminal, exact keys, expected/observed behavior and a sanitized error/screenshot. info describes local preferences/dependencies; it is not a cluster-connectivity test. Automated coverage supports confidence; it does not prove compatibility with every cluster or terminal.