Skip to content

kubelatch CLI

All the commands and flags of kubelatch, the client for people. The step-by-step guide is The CLI; the commands of the server binary (kubelatch-server serve, user …) are in the server CLI.

kubelatch login [<url>] [--device] [--ca-file <pem>] [-o <file>]
kubelatch logout
kubelatch status
kubelatch kubeconfig [--merge] [--alias <id>=<name>]... [-o <file>]
kubelatch request --cluster <id> --role <role> (--namespace <ns> | --cluster-wide)
                  [--for <duration>] --reason <text> [--ticket <ticket>] [--no-wait]
kubelatch request cancel <id>
kubelatch credentials
kubelatch credentials revoke <id>
kubelatch exec-credential
kubelatch version
kubelatch help [<command>]

Messages are in English, like kubectl's. Flags can go before or after the URL.

kubelatch login

Signs you in and writes the kubeconfig. The first time it needs kubelatch's URL; it's saved, and later logins reuse it.

Flag What it does
--device Instead of opening the browser, prints a URL (<url>/cli/device) and a code like BCDF-GHJK to type in any browser where you're signed in. It asks kubelatch every 5 s until someone approves it; the code lasts 10 minutes.
--ca-file <pem> A CA to trust on top of the system's, for a kubelatch with a certificate from a private CA. It's saved with the URL.
-o <file> Writes the kubeconfig to that file instead of ~/.kube/kubelatch.yaml.

Without --device, it listens on a random port of 127.0.0.1, opens the browser on <url>/cli/approve/<id> (and prints that URL, in case the browser doesn't open) and waits up to 5 minutes for the approval. The session lasts what KUBELATCH_CLI_SESSION_TTL says, 12 h by default. A new login revokes the previous session, even against another server (on that old server, with its CA).

kubelatch logout

Revokes the session's credential in kubelatch and deletes session.json. If kubelatch can't be reached, it deletes the local session anyway and exits with 1: the credential stays valid until it expires, so revoke it from the web. Without a session it prints Not signed in. and exits with 0.

kubelatch status

Server, user, session expiry and one line per cluster you have access to: the context, the cluster's name and the permissions (tier, namespace or whole cluster, and the expiry of those that have one).

After the clusters it lists your access requests that still wait for a decision, each with how long ago you asked, when it expires and its link. Nothing is printed when none waits, or when the server can't list them (Free edition, an older server).

kubelatch kubeconfig

Writes the contexts again, for example after a new permission.

Flag What it does
--merge Merges into the file KUBECONFIG names (the first one that exists; the last one if none does) or into ~/.kube/config, instead of writing ~/.kube/kubelatch.yaml. It adds or replaces only the kubelatch-* clusters and contexts and the kubelatch user, removes the kubelatch-* entries of clusters you no longer have access to, and never changes current-context. A file that doesn't parse as a kubeconfig is left alone.
--alias <id>=<name> Names the cluster <id>'s cluster and context kubelatch-<name> instead of kubelatch-<id>. Repeatable; --alias <id>= removes the alias. <name> matches ^[a-z0-9]([a-z0-9-]{0,62})$, and two clusters can't end up with the same name. Saved in aliases.yaml and applied to every later run, with or without --merge; an id with no cluster in your access is kept and reported as a warning. With --merge, the entries under an old alias are removed like any other stale kubelatch-* entry.
-o <file> Writes that file. With --merge, merges into it.

The file has one cluster and one context per cluster, kubelatch-<cluster>, pointing at <url>/clusters/<cluster>, and the user kubelatch with the exec plugin (command: kubelatch, args: [exec-credential], interactiveMode: Never); no token. The certificate-authority-data is kubelatch's own CA (KUBELATCH_KUBECONFIG_CA) or, if it has none, the one from --ca-file. Without --merge, current-context is the first cluster.

kubelatch request

In Pro, asks for a role on a cluster for a while and waits for someone to decide.

kubelatch request --cluster <id> --role <role> (--namespace <ns> | --cluster-wide)
                  [--for <duration>] --reason <text> [--ticket <ticket>] [--no-wait]
kubelatch request cancel <id>
Flag What it does
--cluster <id> The cluster's id. Required.
--role <role> The role to ask for. Required.
--namespace <ns> or --cluster-wide Where the role applies. Exactly one of them.
--for <duration> How long: Go durations plus days (2h, 90m, 1d, 1d12h). Without it, the duration the web form proposes for that role, or what an extension can still add when that is less. An extension that asks for more is refused, with what does fit.
--reason <text> Why you need it. Required.
--ticket <ticket> The ticket that backs it, such as INC-123.
--no-wait Prints the request and exits with 0 without waiting.

It prints the request's link and who decides: the administrators (Waiting for ana or luis to decide.), or the owners of the place with it (Waiting for luis, carmen (owners of prod/pagos) or an administrator to decide., ending in and 3 more past 50 names), the namespace's own owners first. Then it checks every 5 seconds until it is approved, denied, expired or cancelled; Ctrl-C leaves the request pending. The same command over a direct permission you already hold is an extension (Extension of debugger in prod/pagos by 2h). A role the environment grants without approval is granted at once (Granted by the rule of staging: …). When the cluster is new to you, the last line says to run kubelatch kubeconfig. kubelatch request cancel <id> withdraws a request of yours. In Free it prints who to ask and exits with 1.

kubelatch credentials

Lists your credentials: the id (the session's with a *), name, kind (standard or cli), cluster (all or one), expiry, last use and status. kubelatch credentials revoke <id> revokes one of yours; if it's the session's, the session ends too.

kubelatch exec-credential

kubectl runs it, not you. It prints an ExecCredential (client.authentication.k8s.io/v1) with the session's token and expiry, without going to the network:

{"apiVersion":"client.authentication.k8s.io/v1","kind":"ExecCredential","status":{"expirationTimestamp":"2026-09-28T06:12:00Z","token":"klt_…"}}

Without a valid session it exits with 1 and prints, for kubectl to show, error: no kubelatch session: run "kubelatch login" or error: the kubelatch session expired: run "kubelatch login".

kubelatch version and kubelatch help

version prints the version of the release the binary comes from, such as v0.40.0.

help, also -h and --help, lists the commands with a one-line summary (exec-credential listed separately, since kubectl runs it), the environment variables and the exit codes. kubelatch help <command>, or kubelatch <command> -h (also --help), prints that command's usage, description, flags and examples. Help exits with 0; help with an unknown command exits with 2.

A wrong flag or argument prints the error and the command's usage, and exits with 2.

Files and environment

Name What
~/.config/kubelatch/config.yaml The URL and the CA from --ca-file. Mode 0600, in a 0700 folder.
~/.config/kubelatch/aliases.yaml The names --alias gave to contexts: cluster id to name. Only there once you use --alias.
~/.config/kubelatch/session.json The session: token, credential id, login and expiry. Mode 0600. logout deletes it, and so does any command that finds it expired or refused by kubelatch.
~/.kube/kubelatch.yaml The kubeconfig of login and kubeconfig, with no secrets.
KUBELATCH_CONFIG_DIR Changes the folder of the first three.
KUBECONFIG Where kubeconfig --merge writes.

What the session's token can reach is in the security model.

Exit codes and errors

Code When
0 The command finished successfully.
1 It failed: no session, kubelatch unreachable, an error from the API.
2 Invalid arguments or unknown command.
3 kubelatch request: the request was denied.
4 kubelatch request: the request expired or was cancelled.

Common messages:

Message What it means
no kubelatch session: run "kubelatch login" You haven't signed in, or you signed out.
the kubelatch session expired: run "kubelatch login" 12 h have passed (or whatever KUBELATCH_CLI_SESSION_TTL says).
the kubelatch session is no longer valid (revoked or expired on the server): run "kubelatch login" The credential was revoked from the web, or your account was disabled.
the first login needs kubelatch's URL: kubelatch login https://kubelatch.example.com No URL is saved yet. Exit code 2.
cannot reach kubelatch at …: … Network or TLS. With x509: certificate signed by unknown authority, log in again with --ca-file.
refusing plain http to … The URL is http:// and not localhost.
the login was cancelled in the browser Someone clicked Cancel on the approval page.
no approval came from the browser within 5m0s: … Nobody approved it in time; try again, or use --device.
the code expired before anyone approved it: run kubelatch login --device again The 10 minutes of the --device code ran out.
this sign-in request has expired or was already used: run kubelatch login again kubelatch no longer knows the request: it expired on the server, or it was cancelled.

Binaries

Every release attaches kubelatch for Linux and macOS on amd64 and arm64: kubelatch_<version>_<os>_<arch>.tar.gz and kubelatch_<version>_checksums.txt, shared with kubelatch-server. How to install it is in The CLI.