Server CLI¶

All the subcommands and flags of the kubelatch-server binary. The same binary is the server and the account-rescue tool. The client for people is a different binary, kubelatch: see kubelatch CLI.

kubelatch-server [serve]
kubelatch-server user create <login> [--admin] [--break-glass] [--display-name <name>] [--password-stdin]
kubelatch-server user set-password <login> [--password-stdin]
kubelatch-server user set-break-glass <login> [--off]
kubelatch-server license show
kubelatch-server license verify <file>
kubelatch-server version
kubelatch-server help [serve | user [<subcommand>] | license [<subcommand>]]

How it runs¶

The user subcommands read the same environment variables as the server, with the same rules: they need at least DATABASE_URL, KUBELATCH_BASE_URL and KUBELATCH_ENCRYPTION_KEY. They apply pending migrations, write straight to the database, and record the action as a control event with no actor. There's no need to stop the server, and it doesn't matter which replica they run on.

They never talk to GitHub. They validate the GITHUB_* variables like the server (an incomplete block also fails them), but only use their presence, to know whether GitHub login is active.

On Kubernetes, run them inside the pod, always with the management cluster's explicit kubeconfig. The image has no shell: the binary is at /kubelatch-server.

kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -it deploy/kubelatch -- /kubelatch-server user create admin --admin

Flags go after the login.

Binaries¶

Every release attaches kubelatch-server to its GitHub Release, with the web UI embedded, for Linux and macOS on amd64 and arm64:

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

Check the download before extracting it, in the directory where both files are:

sha256sum --ignore-missing -c kubelatch_<version>_checksums.txt

The container image ghcr.io/picaportelabs/kubelatch is published for linux/amd64 and linux/arm64 with the same binary at /kubelatch-server.

kubelatch-server and kubelatch-server serve¶

Starts the server: control plane, proxy, reconciler and background jobs. With no arguments it does the same. It takes no flags: everything is configured with environment variables. serve -h (or --help) prints its help without starting it.

kubelatch-server serve

Writes JSON logs to standard output (or key=value text, see KUBELATCH_LOG_FORMAT). Exits with code 1 if the configuration is invalid or it fails to start. On SIGTERM or Ctrl-C it stops accepting connections, gives in-flight requests 3 s, cuts open streams, and exits within 30 s at most.

kubelatch-server user create¶

Creates a person with a password. It's how you create the first administrator.

The login accepts only lowercase letters, digits, ., _ and -, 1 to 63 characters. A login is never reused, even if the previous account is disabled. The password must be 12 to 128 characters and different from the login.

kubelatch-server user create admin --admin
kubelatch-server user create rescue --admin --break-glass --display-name "Rescue account"

Output:

user admin created (id 0192…, admin=true, break_glass=false)

With GitHub active and a non-break-glass account, it adds a warning: that password won't work to sign in.

kubelatch-server user set-password¶

Sets a new password for an existing person. It also unlocks the account, revokes its pending links, and closes all its sessions. It's the rescue path when nobody can sign in.

kubelatch-server user set-password admin

Output:

password set for admin; account unlocked and sessions closed

With GitHub active, the password only works if the account is break-glass. If it isn't, the command warns about it and suggests kubelatch-server user set-break-glass.

kubelatch-server user set-break-glass¶

Marks an existing person as a break-glass account, or unmarks them. It's the only way to do it: neither the interface nor the API can.

kubelatch-server user set-break-glass admin
kubelatch-server user set-break-glass admin --off

Output:

break_glass=true for admin

kubelatch refuses to unmark the last administrator who can sign in.

kubelatch-server license show¶

Prints the edition in force: the key's source (KUBELATCH_LICENSE or the one pasted in Edition), its customer, seats and expiry, the limits that apply and what the instance holds. It reads the same environment as the server and applies pending migrations.

kubelatch-server license show

Output:

edition: pro
status: pro
source: env
license: 7f3c…
customer: Acme S.L.
seats: 40
trial: false
expires: 2027-10-06T12:00:00Z
grace until: 2027-11-05T12:00:00Z
limits: clusters unlimited, people 40, custom roles unlimited, retention as configured
usage: people: 12, clusters: 4, custom roles: 2

kubelatch-server license verify <file>¶

Checks a key file against the public keys built into this binary, without a database, and prints what the key says. An expired key still verifies, and the first line says whether it is valid, in its grace period or lapsed. Exit code 1 when the key does not verify. Give it the path of a file: a key typed where the path belongs is a usage error (exit code 2) whose message never repeats what you typed.

kubelatch-server license verify kubelatch-pro.jwt

kubelatch-server version¶

Prints the version the image was built with (dev on a local binary).

kubelatch-server version

kubelatch-server help¶

Prints the usage summary. Also responds to -h and --help.

Help exits with 0; an unknown topic or subcommand, with 2.

Passwords via standard input¶

Without --password-stdin, the command asks for the password twice through the terminal, without echo. If standard input is not a terminal, it fails and asks you to use --password-stdin.

With --password-stdin, everything that arrives on standard input is the password, minus one trailing newline (\n or \r\n). So echo and printf '%s\n' work as is. A password that ends in a newline is passed with two.

printf '%s\n' "$PASSWORD" | kubectl --kubeconfig "$MGMT_KUBECONFIG" -n kubelatch exec -i deploy/kubelatch -- /kubelatch-server user set-password admin --password-stdin

Exit codes and errors¶

Common error messages: