Authentication

Ringleader uses a multi-origin model: you can sign in to one or more control planes, called origins, and work across them from one CLI. The auth commands manage those origins and create bearer tokens for the HTTP API.

rl auth status

Show the current identity and federated control-plane origins: a “whoami” for the multi-origin model. It is control-plane-optional and never fails on an unreachable origin.

rl auth status
rl auth status -o json        # adds daemon health + per-origin details
rl auth status --show-access  # what you're allowed to do at each origin

When a session expires

Most of the time you stay signed in without noticing, because your session renews itself in the background. Occasionally it cannot, usually after a laptop has been asleep for a long stretch, and you are signed out for real. Signing in again is the only fix.

rl auth status says so, and names the command to run:

Origins:
  cp1                https://cp.example.com                  logged in  alice@example.com
             warning: session expired: sign in again: rl auth login https://cp.example.com

In -o json, the origin carries "needsReauth": true.

Every other command that reads from that origin reports the same thing rather than a generic failure:

warning: origin "cp1": session expired or not authenticated; run `rl auth login https://cp.example.com`

The macOS app and the Windows tray show a Session expired notice with a Sign in again button that reruns the login against that origin.

An unreachable origin is a different, transient thing and never prompts you to sign in again; nor does a permission denial, which re-authenticating would not fix.

rl auth login [url]

Register a control plane as a federated origin. By default this runs an interactive device-code flow and stores access + refresh tokens. With no URL, it signs in to https://app.ringleader.dev.

# Interactive device-code login to Ringleader's own control plane.
rl auth login

# The same, against another control plane.
rl auth login https://your-control-plane.example.com

# CI, with no stored secret: become a service account by exchanging
# the job's own workload identity.
rl auth login https://cp.example.com \
    --service-account dev/ci --provider acmecorp-github

# Non-interactive with a static bearer token.
rl auth login https://cp.example.com --token "$RL_TOKEN" --name ci

# Loopback / unauthenticated control plane.
rl auth login http://127.0.0.1:8080 --anonymous

--service-account works only where something can prove who the process is. That means one of these:

• A GitHub Actions job with permissions: {id-token: write}.
• A host running a SPIRE agent that has a registration entry for the process.
• A Ringleader workstation that holds the sa:assume capability.

On a laptop there is nothing to exchange. See ServiceAccount for the objects it needs.

rl auth logout [origin-name]

Remove a federated control plane by its local name. With no name, it logs out of your only origin, and asks you to name one when you have several.

Before it removes the origin, logout copies the WorkstationConfigs and Grants you own there back to this device. Objects other people own stay on the control plane. A login made with --anonymous, or with a --token that names no user, has no known identity. Nothing is copied back then, and logout prints a warning. If the control plane cannot be reached, logout removes it without copying anything.

rl auth logout ci

rl auth token

Create a bearer token for the HTTP API, signed with the data directory’s signing key. A daemon started from the same data directory with --addr accepts it. With no --as, the token is for the current user.

rl auth token                       # current user, 1h
rl auth token --as sa:dev/builder --ttl 24h