Command reference
Global flags on every command: --endpoint URL, --target NAME (alias --context), -o text|json.
kobe --help lists the commands by task. kobe <command> --help shows a command's flags, and -h gives the short form.
Quick reference
| Command | Description |
|---|---|
kobe status | Endpoint status, auth methods, pools, your leases |
kobe version | CLI and endpoint versions |
kobe login | Authenticate (--device for headless) |
kobe logout | Drop stored credentials and revoke OIDC tokens at the IdP |
kobe lease [pool] | Lease from a pool |
kobe extend [lease] | Add time to an active lease |
kobe release [lease] | Release a lease |
kobe purge | Release all active leases and remove local kubeconfigs |
kobe with-lease <pool> -- <cmd> | Cluster lease around one command, then release |
kobe run <pool> -- <cmd> | Sandbox: create, run one command, release (details) |
kobe flake init | Write flake.nix for a sandbox lease |
kobe flake list [lease] | List packages installed by kobe lease --flake |
kobe exec <lease> -- <cmd> | Run a command in a lease that supports exec (--detach to return once it starts) |
kobe logs <lease> | Read output from a lease that supports logs |
kobe cancel <lease> --execution <id> | Cancel a running execution |
kobe attach [lease] | Interactive session through attach |
kobe port-forward <lease> <spec> | Forward a declared port |
kobe vnc open <lease> | Start the desktop and open a viewer (details) |
kobe vnc screenshot <lease> | Write the Sandbox desktop to a PNG |
kobe vnc click|move|type|key <lease> | Drive that desktop |
kobe init | Set this machine up for ssh kobe-<pool>-<name> (details) |
kobe doctor | Read-only checks for ssh kobe-… |
kobe ssh-config | Print the ssh_config block |
scp, sftp, rsync | Copy files to and from a sandbox (details) |
kobe config | Edit the CLI configuration |
kobe target … | List, switch, and define named targets |
kobe completions <shell> | Print a shell completion script |
kobe status
kobe status
kobe status --all
Queries GET /v1/status. Shows operator version, auth methods, your leases, and pool summary. GET /v1/status itself does not require authentication; lease and pool rows do.
Text output hides released and expired leases. Pass --all to list them. JSON (-o json) hides them too unless --all is set.
Authenticated pool rows include the pool phase and a quarantined count. A non-zero count means cleanup evidence is incomplete and that capacity remains withheld.
kobe version
kobe version
Prints the local CLI version and, when reachable, the endpoint version from GET /v1/status.
kobe login
kobe login
kobe login --device
Authenticates with the configured endpoint:
ssh— challenges your SSH agent to sign with your Ed25519 keytoken— validates the token set in config orKOBE_TOKENoidc— opens a browser (default) or prints a URL and code with--device(RFC 8628)
On success, kobe stores a session token locally.
kobe pins each endpoint's auth issuer and audience on first contact and refuses
a later change. When the change is expected, for example after the server moved
from SSH keys to OIDC, run kobe login --retrust once: it shows the old and new
values and pins the ones the server advertises now.
kobe logout
kobe logout
Removes stored credentials. For OIDC, also revokes refresh and access tokens at the IdP (RFC 7009).
kobe lease
kobe lease [pool] [--ttl <duration>] [--kubeconfig <path>] [--name <alias>] [--ensure] [--keepalive] [--no-wait] [--wait-timeout <duration>] [--metadata-json <json|@path>] [--flake <dir>]
Creates a lease. The pool's resource kind decides what you get: a kubeconfig for Cluster, exec/logs/attach for Sandbox.
If you omit the pool, the CLI picks when you have one default, or opens a picker (JSON mode errors and lists candidates).
kobe lease ci-small
kobe lease ci-small --ttl 30m
kobe lease ci-small --kubeconfig /tmp/kube.yaml
kobe lease agents --ttl 30m
kobe lease ci-small --name pr-3835 --ensure
kobe lease ci-small --keepalive
kobe lease ci-small --metadata-json '{"github":{"pullRequest":3835}}'
kobe lease ci-small --metadata-json @lease-metadata.json
kobe lease ci-small --no-wait
kobe lease agents --name dev --flake .
Prints the lease ID, resource kind, capabilities, and expiry. While waiting, Ctrl-C stops waiting and prints kobe release <id>; it does not release the lease.
If the CLI is older than the operator, kobe status and kobe lease print a warning.
For a Cluster pool, kobe lease and kobe with-lease send one idempotency key per run. When the server answers that another create for the same identity is still being admitted (common when a CI matrix starts many jobs at once), or that it is overloaded, the CLI waits for Retry-After plus some jitter and tries again with the same key. It prints each retry on stderr and gives up after --wait-timeout, or after 2 minutes when that flag is unset.
| Flag | Default | Description |
|---|---|---|
--ttl | 1h | Requested TTL. Capped by AccessPolicy maxTtl. |
--kubeconfig | ~/.kube/kobe-<pool>-<short-id>.yaml | Cluster only: path to write the kubeconfig. |
--name | unset | Alias unique among your active leases. |
--ensure | disabled | With --name, reuse that active lease (extend TTL) instead of failing. Original metadata is kept. |
--keepalive | disabled | Heartbeat-extend by --ttl at half-TTL intervals until interrupted. Conflicts with --no-wait. |
--no-wait | disabled | Return after creating the lease. |
--wait-timeout | unset | Maximum time to wait for the lease to become usable. |
--metadata-json | unset | Opaque JSON object, inline or @path. Cluster leases only. Bounded by the server. Never include secrets. |
--flake | unset | Directory with flake.nix. After a Sandbox is Ready, installs that flake. Cannot be combined with --no-wait. |
With --flake, the command waits until a Sandbox is Ready, then installs that directory's flake.nix. Details: Executable resource commands.
kobe flake
kobe flake init
kobe flake list [lease]
init writes flake.nix in the current directory and refuses to overwrite one. list runs nix profile list in a lease. With one lease, the name is optional.
kobe extend
kobe extend [--ttl 30m]
kobe extend <lease-id-or-pool> --ttl 1h
Adds --ttl (default 30m) to the current expiry, subject to maxExtensions and the policy ceiling. With no selector, uses your only active lease or opens a picker (JSON mode lists candidates and exits).
A running kobe exec keeps the deadline it started with. For a Sandbox lease, kobe extend names each running execution that still stops before the new expiry.
kobe release
kobe release [lease-id]
Releases immediately. Omit the id when you hold a single active lease.
kobe purge
kobe purge
kobe purge -y
kobe purge --orphans-only
Without --orphans-only, releases every active lease for this identity and deletes kubeconfig files kobe recorded for this endpoint. --orphans-only only removes kubeconfigs whose leases are already Released, Expired, or absent. Files in ~/.kube/kobe-*.yaml that kobe never recorded are left alone. -y skips the confirmation prompt.
kobe with-lease
kobe with-lease <pool> [--ttl 1h] [--metadata-json <json|@path>] -- kubectl get nodes
Cluster only. Creates a lease, heartbeat-extends it for the command's lifetime, puts the kubeconfig in KUBECONFIG, then releases on exit (success, failure, or signal). The pool must expose kubeconfig. For sandboxes, use kobe run.
Executable commands
kobe run, exec, logs, cancel, attach, and port-forward are documented in executable resource commands. kobe vnc is in desktop commands. kobe init, doctor, ssh-proxy, and ssh-config are in SSH.
kobe config
kobe config # opens the editor
kobe config edit [name]
kobe config view
kobe config export [path]
kobe config import [path]
Bare kobe config opens the terminal editor for the current target. Without a terminal, such as in a script or with -o json, it prints its subcommands and exits 2. view shows the resolved configuration and where each value came from. export and import take - for stdout and stdin.
kobe target
kobe target # same as kobe target list
kobe target list
kobe target current
kobe target use work
kobe target set work --endpoint https://kobe.example.com --auth ssh --global
target set writes ./.kobe.toml unless you pass --global (~/.config/kobe/config.json). --auth is none, token, oidc, or ssh. --token is required for token auth. --default-pool is the pool ssh kobe-<name> uses when the host does not name one.
target use switches the target for the current shell only. Other terminals keep theirs. Use --target NAME for a single command.
kobe config list, current, use, and set still work as the older spellings of these commands.
See Configuration.
kobe completions
kobe completions bash|zsh|fish|elvish|powershell
Prints a completion script generated from the installed CLI. Load it from your shell's startup file:
source <(kobe completions zsh) # ~/.zshrc
source <(kobe completions bash) # ~/.bashrc
kobe completions fish | source # ~/.config/fish/config.fish