Authentication
How orl signs you in (a browser device login, or an API key for scripts and CI), picks your organization, and which setting wins when several are set.
orl holds one of two credentials: a user session, from signing in as yourself, or an
API key, the same key the REST API uses. A session can do everything a
key can, plus the organization actions a key can never perform (member, billing, key and role
management), with your own permissions, nothing more.
Sign in
orl auth loginOn a terminal this runs a device login: orl opens your browser (or, with --no-browser, just
prints a URL and a 6-digit code) to a page where you approve the request and pick which
organization to sign the CLI into.
orl prints a 6-digit code and opens (or shows) the approval page.
On the approval page, confirm the code matches the one in your terminal before continuing: a link with the code pre-filled is not enough on its own, because the device asking to be approved might not be yours. The page also shows the requesting device's name, address, and request time.
Pick the organization to sign in to, and the role the session acts with, and approve.
orl picks up the result and stores a 30-day session in your OS keyring.
Same permissions as the dashboard, limited to the role you pick
A session acts with a role in the organization you picked: Member by default when you can give it, otherwise your own role, exactly like the dashboard's own member management. Owner is never given to a session.
orl auth status # the kind (session or key), the role, the org, and the expiry
orl account whoami # the principal and the org it acts inList or revoke a session from any device at Account > CLI sessions in the dashboard, or
revoke the current one with orl auth logout.
Choosing a role
--role <id> asks the approval page to preselect a role for the session, a built-in role up to
Admin (admin, member, billing, viewer) or a custom role id:
orl auth login --role adminThe page only preselects a role it is already offering: it never widens what you could grant
someone yourself, and it never offers Owner. Member is the default because it covers building and
running workloads and calling inference; some organization actions need more. An agent that adds
funds with orl billing deposit, for example, needs billing write, which Member does not have, so
sign in with --role admin (or a custom role with that permission) first.
orl auth status shows which role a session actually got, separately from your own:
$ orl auth status
...
session role: Admin
your role: OwnerFor scripts and CI: an API key
A device login needs a human in a browser, so scripts, CI, and agents use an API key instead (create one in the dashboard under Account > API Keys):
echo "$OPENRELAY_API_KEY" | orl auth login --with-token--with-token reads the key from stdin and skips the device flow entirely. Non-interactively
(no terminal attached), orl auth login without --with-token refuses rather than hanging, since
there is no browser for it to open.
A key's org is fixed
Each API key is bound to one organization at creation, so orl reads the org from the key and you
never pass --org. A session's org is chosen when you approve it instead, and can be a different
org each time you sign in.
Where the credential is stored
Either way, orl auth login uses your operating system keyring (macOS Keychain, GNOME Keyring /
libsecret, Windows Credential Manager). The plaintext never lands in a config file.
On a headless box with no keyring, orl refuses to write plaintext unless you opt in:
orl auth login --with-token --insecure-storageThat writes the key to a 0600 file in the config directory. Prefer the OPENRELAY_API_KEY
environment variable in CI instead (below); a session credential is not meant for CI at all, since
nothing can re-approve it unattended once it expires.
Where the credential is sent
A stored credential only ever reaches the configured API host and the inference host derived from
it (api.<domain> → inference.<domain>). Pointing OPENRELAY_INFERENCE_URL at anything else
gets no credential from the store: orl refuses the request rather than send it there bare. Pass a
key explicitly for that one call instead (OPENRELAY_API_KEY, or --api-key), which does reach
whatever host you point it at.
Configuration precedence
For each setting, orl takes the first source that is set:
| Setting | Flag | Environment | Stored / default |
|---|---|---|---|
| Credential | --api-key | OPENRELAY_API_KEY | keyring / consented file |
| Organization | --org | OPENRELAY_ORG_ID | resolved from the credential |
| API base URL | --api-url | OPENRELAY_API_URL | https://api.openrelay.inc |
So a flag beats an environment variable, which beats what orl auth login stored. In CI, set
OPENRELAY_API_KEY and skip orl auth login entirely.
Log out
orl auth logoutRemoves the stored credential for the current API host. For a session, this also revokes it on the server first, so it stops working everywhere at once, not just on this device. To rotate an API key, create a new one in the dashboard, log in again, then revoke the old one.
Quickstart
Sign up, log in, and get a GPU VM running with the orl CLI in four commands, then connect to it, watch its spend, and stop it when you are done.
Workflows
The signature orl commands for deploying and connecting to GPU VMs and watching spend, plus how to script orl in CI with JSON errors and exit codes.