CLI Reference

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

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/release-finalizer/get-resolved-configuration, shell, code, tmux, logs, troubleshoot.
  • File transfer: file cp, moving files to and from a workstation.
  • 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 create/enable/disable, forwarding a local key into workstations.
  • Reusable content: configmap create/get/edit, the text a config’s scripts/files can reference.
  • Daemon: daemon start, stop, restart, status and log-level. The page also covers rl status, which reports the workstation providers this machine can use.
  • Docs bundle: docs, the embedded, offline documentation bundle.
  • TUI: tui, a full-screen dashboard over your resources (full walkthrough in the Terminal UI section).

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

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:

  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 "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.

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, 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.