Skip to content
Skip to Content
Commands

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

CommandDescription
kobe statusEndpoint status, auth methods, pools, your leases
kobe versionCLI and endpoint versions
kobe loginAuthenticate (--device for headless)
kobe logoutDrop 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 purgeRelease 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 initWrite 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 initSet this machine up for ssh kobe-<pool>-<name> (details)
kobe doctorRead-only checks for ssh kobe-…
kobe ssh-configPrint the ssh_config block
scp, sftp, rsyncCopy files to and from a sandbox (details)
kobe configEdit 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 key
  • token — validates the token set in config or KOBE_TOKEN
  • oidc — 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.

FlagDefaultDescription
--ttl1hRequested TTL. Capped by AccessPolicy maxTtl.
--kubeconfig~/.kube/kobe-<pool>-<short-id>.yamlCluster only: path to write the kubeconfig.
--nameunsetAlias unique among your active leases.
--ensuredisabledWith --name, reuse that active lease (extend TTL) instead of failing. Original metadata is kept.
--keepalivedisabledHeartbeat-extend by --ttl at half-TTL intervals until interrupted. Conflicts with --no-wait.
--no-waitdisabledReturn after creating the lease.
--wait-timeoutunsetMaximum time to wait for the lease to become usable.
--metadata-jsonunsetOpaque JSON object, inline or @path. Cluster leases only. Bounded by the server. Never include secrets.
--flakeunsetDirectory 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
Available for:
Apple macOS logomacOSMicrosoft Windows logoWindowsLinux logoLinux
Download Kunobi