CLI Reference | Ringleader Docs

The rl CLI is how you drive Ringleader. Everything you do, from signing in to booting a cloud VM, is a command on this page.

If you installed the macOS native app, the rl binary is already on your PATH (symlinked to /usr/local/bin/rl). The Windows installer adds it to the machine PATH.

Note

The CLI is named rl. The longer ringleader name remains available as a permanent alias on every platform, so existing scripts keep working unchanged. The two are interchangeable; this documentation uses rl throughout.

Command groups

Every resource kind gets a command group of the same name, and the grammar is rl <kind> <verb> (e.g. rl workstation get, rl secret create). The generic verbs and the cross-cutting apply mirror kubectl. Commands fall into a few families:

Authentication: auth login, auth logout, auth status, auth token.
Service accounts: serviceaccount create/trust, the non-human identities CI signs in as.
Resource verbs: apply, diff, and the per-kind get, describe, create, edit, copy, delete, wait.
Imperative create: the rich generators namespace create, secret create, workstation create, configmap create and sshkey create.
Workstation lifecycle & access: workstation start/stop/restart/cordon/uncordon/release-finalizer/get-resolved-configuration/egress, shell, code, tmux, logs, troubleshoot.
Workstation pools: workstationpool create/lease/usage and workstationpoollease renew/release, workstations built from one template and leased out one at a time.
File transfer: file cp, moving files to and from a workstation.
Sharing & access: workstation share/unshare/access, secret share/unshare/access, workstationpool share/unshare/access, and share show/enable/disable.
Local bindings: binding show, enable, disable, switch, browser-opens.
SSH keys: sshkey create/enable/disable, forwarding a local key into workstations.
Reusable content: configmap create/get/edit, the text a config’s scripts/files can reference.
Organizations: org get/describe/create/edit, the company your namespaces belong to.
Daemon: daemon start, stop, restart, status and log-level. The page also covers rl status, which reports the workstation providers this machine can use.
Images: image list and image delete, the OS images cached on this computer.
Local runtime: local-runtime create/status/delete, the local container runtime your docker command talks to. Its default-socket form is in The app’s pages.
Docs bundle: docs, the embedded, offline documentation bundle.
TUI: tui, a full-screen dashboard over your resources (full walkthrough in the Terminal UI section).

A few commands stand apart from the groups:

rl version prints the CLI version and the version of the in-VM agent it expects on a workstation. rl --version and rl -v print the same.
rl version --check first asks the control plane you are signed in to whether a newer client is available. It exits 1 if it cannot ask, and it reports that there is nothing to check when you are not signed in.
rl licenses prints the license notices for the third-party software built into rl. The notices ship inside the binary, so it works offline.
rl completion <shell> generates a shell completion script.

While you are signed in, a running daemon asks the same question when it starts and then once an hour. When the answer is yes, rl version and rl auth status add a line such as a newer client is available: 0.48.0 (you have 0.47.1).

Common flags

Most commands accept these flags:

Flag	Description
`--home <dir>`	Data directory (default `$RINGLEADER_HOME`, else `~/.ringleader`).
`-n, --namespace <ns>`	Target namespace. Defaults to the namespace pinned on this device, else your primary origin’s default namespace, else `local`.
`-A, --all-namespaces`	Operate across every namespace you can see.
`-o, --output <format>`	Output format: `table` (default for `get`), `yaml`, `json`, or `jsonpath='{.path}'`.
`--as <subject>`	Impersonate a subject (e.g. `user:alice`, `sa:builder`). Requires the right to do so.

Exit codes

Code	Meaning
`0`	Success.
`1`	Command error (the operation failed).
`2`	Usage or flag error.
`3`	`daemon status` only: no daemon is running (scriptable, like `systemctl`).

Namespaces and resolution

Your namespace is created the first time you sign in, not before, and the control plane decides which one you land in. Working locally without signing in, you get the reserved local namespace, which also holds the local container runtime.

When you omit -n, the CLI resolves the namespace in this order, highest first:

an explicit -n / --namespace on the command;
the namespace pinned on this device with rl namespace use;
your primary origin’s spec.defaultNamespace, assigned at login;
the reserved built-in local.

`rl namespace use [namespace]`

Pin the namespace that bare commands target on this device, so you stop typing -n on every command. With no name, it reports the answer and which rung of the ladder produced it.

rl namespace use team-a       # pin it
rl namespace use              # what do bare commands target, and why?
rl namespace use --unset      # drop the pin, follow the origin's default again

$ rl namespace use team-a
namespace pinned to "team-a"

$ rl namespace use
team-a (pinned on this device)

$ rl namespace use --unset
namespace pin cleared; commands now target "platform" (from origin "cp1")

The part in parentheses matters. local (the built-in default) and local (pinned on this device) are the same namespace for different reasons, and only the first tells you that no login ever assigned you one.

Flag	Description
`--unset`	Clear the pin and follow the origin’s default again.
`--home <dir>`	Data directory.

Notes:

The pin is device-local. It never federates, and it survives rl auth login and rl auth logout, so a login cannot re-target a user who has chosen otherwise.
It sits below -n, so a per-invocation override still wins.
It works in standalone mode, where there is no origin at all.
Only the shape of the name is checked. You can pin a namespace you cannot yet read; the next command reports an ordinary not-found that names it.
Set and show are one verb, like git config. rl ns use is the same command.