The CLI¶

The kubelatch CLI signs you in once and gives kubectl, k9s, Lens and Helm their credential on its own. You don't copy tokens or download kubeconfigs: the CLI writes a kubeconfig with no secret in it, and kubectl asks the CLI for the token each time it needs one.

Install it¶

Every release carries kubelatch for Linux and macOS, on amd64 and arm64:

• kubelatch_<version>_<os>_<arch>.tar.gz, with the binary inside;
• kubelatch_<version>_checksums.txt, the SHA-256 of every file of the release.

Check the download and put the binary in your PATH. For example, on Linux amd64:

VERSION=0.2.0   # the release you downloaded, without the v
sha256sum --ignore-missing -c kubelatch_${VERSION}_checksums.txt
tar -xzf kubelatch_${VERSION}_linux_amd64.tar.gz kubelatch
install -m 0755 kubelatch ~/.local/bin/kubelatch
kubelatch version

On macOS, check it with shasum -a 256 --ignore-missing -c instead of sha256sum.

kubectl runs kubelatch by name, so it has to be in the PATH of the shell where you use kubectl.

Sign in¶

The first time, give it kubelatch's URL, the one you open in the browser:

kubelatch login https://kubelatch.example.com

The CLI opens your browser on a page that asks Approve the sign-in from alice-laptop? If you aren't signed in to the web, it asks you to sign in first. The page lays out the request you are approving. It answers as you (You answer as alice. Not you?, with a Sign out link for whoever shares your browser). Under Who asks it shows your computer's name (Computer (as the CLI names it)), From which IP the request came and whether that is the same network as this browser or another network than this browser, and when it was Asked, with a countdown. Under What it gets · until when it says what approving issues: A credential for all your clusters, For 12 h. Click Approve only if you just ran kubelatch login yourself: the line above the buttons says so, and when the request comes from another network than your browser that line turns into a highlighted warning. If the countdown reaches zero, the buttons give way to This request expired: run kubelatch login again. The browser goes back to the CLI, which finishes on its own:

Approve this login in your browser:
  https://kubelatch.example.com/cli/approve/0192…?state=…
Signed in to https://kubelatch.example.com as alice; the session expires 2026-09-28 08:12 CEST.
Wrote 2 context(s) to /home/alice/.kube/kubelatch.yaml. Use it with:
  export KUBECONFIG=/home/alice/.kube/kubelatch.yaml
  kubectl get pods
or merge them into your kubeconfig with "kubelatch kubeconfig --merge".

If the browser doesn't open, open the URL the CLI printed; it waits 5 minutes. If you have to sign in on the way, with a password or with GitHub, the web brings you back to the approval page afterwards. The URL of kubelatch is saved, so later logins are just kubelatch login. Each login replaces the previous session on this machine: the old session is revoked, even if it was on another kubelatch.

Without a browser on this machine¶

On a server over SSH, or anywhere the CLI can't open a browser, use --device:

kubelatch login --device

Open https://kubelatch.example.com/cli/device in a browser where you are signed in to kubelatch and enter the code:

  BCDF-GHJK

Waiting for the approval...

Open that page on any device, type the code under Code shown in the terminal and click Continue. The page then shows the same request as above, with the computer's name and the network it came from: check them and click Approve. The code lasts 10 minutes. If the page shows a request that isn't yours (a mistyped code), click Use another code to type it again; Cancel refuses that request instead.

A private certificate¶

If kubelatch uses a certificate from a private CA, give the CLI that CA once:

kubelatch login https://kubelatch.example.com --ca-file company-ca.pem

The CLI saves it with the URL, trusts it on top of the system's, and puts it in the kubeconfig when kubelatch doesn't publish a CA of its own. The CLI only talks HTTPS; plain http:// is accepted only for localhost and 127.0.0.1, for development.

Point your tools at the kubeconfig¶

kubelatch login writes ~/.kube/kubelatch.yaml, with one context per cluster you have access to, called kubelatch-<cluster>, all with the user kubelatch (abridged):

users:
- name: kubelatch
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: kubelatch
      args:
      - exec-credential
      interactiveMode: Never

There's no token in the file. Each time kubectl needs one, it runs kubelatch exec-credential, which reads it from your session. Point your tools at the file:

export KUBECONFIG=~/.kube/kubelatch.yaml
kubectl config get-contexts
kubectl --context kubelatch-prod get pods

k9s and Helm read the same KUBECONFIG. Lens does too, but as a desktop app it may not see your shell's PATH and fail to find kubelatch; if that happens, give Lens a kubeconfig issued from the web (Get a credential). What doesn't work through kubelatch is in kubectl, k9s, Lens and Helm.

Merge into your usual kubeconfig¶

To have the contexts next to your others:

kubelatch kubeconfig --merge

It writes into the file KUBECONFIG names (the first one that exists, as kubectl does) or into ~/.kube/config. It only adds or replaces the kubelatch-* clusters and contexts and the kubelatch user, removes the kubelatch-* entries of clusters you no longer have, and never changes current-context. Switch with kubectl config use-context kubelatch-<cluster>.

After a new permission¶

The contexts are fixed when the file is written. When an administrator grants you access to another cluster, write them again:

kubelatch kubeconfig            # or: kubelatch kubeconfig --merge

-o <file> writes somewhere else.

Check your session¶

kubelatch status

Server:   https://kubelatch.example.com
User:     alice
Session:  expires 2026-09-28 08:12 CEST (in 11h58m)

CONTEXT         CLUSTER      ACCESS
kubelatch-kind  kind local   viewer (default), debugger (default)
kubelatch-prod  Production   viewer (whole cluster)

On Home, the line under the title says the same: Connected from alice-laptop, until when the session lasts, with Sign out and Connect an agent beside it; the context of each cluster is in its header under My access. kubelatch credentials lists your credentials (the session's has the kind cli and a * next to its id), and kubelatch credentials revoke <id> revokes one of them.

Sign out¶

kubelatch logout

It revokes the session's credential in kubelatch and deletes it from your machine. If kubelatch can't be reached, the local session is deleted anyway and the CLI tells you to revoke the credential from the web, where it stays valid until it expires. From then on kubectl fails with:

error: no kubelatch session: run "kubelatch login"

When the session expires¶

The session lasts 12 h (an administrator changes it with KUBELATCH_CLI_SESSION_TTL), and it isn't renewed on its own. When it expires, kubectl shows error: the kubelatch session expired: run "kubelatch login". Run kubelatch login and carry on: the kubeconfig doesn't change.

Revoking the credential from the web (on Home, Sign out in the line under the title, or Revoke on the row CLI session on … under My credentials) or disabling your account also ends the session: the next request gets a 401, and the next kubelatch command asks you to log in again.

Where it keeps things¶

KUBELATCH_CONFIG_DIR changes the folder of the first two. What the session token can and can't do is in the security model; every command and flag, in the kubelatch CLI reference.