CLI Reference

Every rl command and subcommand, with flags, arguments, and examples.

The rl CLI is the single way to drive Ringleader. It is a pure client of an in-process API server over a local store. There is no imperative side door. Everything you do, from logging in to booting a cloud VM, goes through 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 is a command group named after the kind, 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.
  • Workstation lifecycle & access: workstation start/stop/restart, shell, code, tmux, logs, troubleshoot.
  • Sharing & access: workstation share/unshare/access, secret share/unshare/access, and share show/enable/disable.
  • Local bindings: binding show, enable, disable, switch, browser-opens.
  • SSH keys: sshkey enable/disable, forwarding a local key into workstations.
  • Daemon: daemon start, stop, restart, status.
  • Docs bundle: docs, the embedded, offline documentation bundle.
  • TUI: tui, the k9s-style management terminal UI (full walkthrough in the Terminal UI section).

rl version prints the CLI version; rl completion <shell> generates a shell completion script.

Common flags

Most commands accept these flags:

FlagDescription
--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-namespacesOperate 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

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

Namespaces and resolution

Ringleader does not seed a per-user namespace eagerly. The control plane assigns your namespace on first login (whoami provisions the namespace and RBAC). In standalone-local mode the reserved default namespace is local, which also holds the product-owned local container runtime.

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

  1. an explicit -n / --namespace on the command;
  2. the namespace pinned on this device with rl namespace use;
  3. your primary origin’s spec.defaultNamespace, assigned at login;
  4. 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 "ringleader-dev" (from origin "stg")

The provenance suffix matters: local (the built-in default) and local (pinned on this device) are the same namespace for opposite reasons, and only the first tells you a login never resolved one for you.

FlagDescription
--unsetClear 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 — 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.