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 approve.
orl picks up the result and stores a 30-day session in your OS keyring.
Same permissions as the dashboard
A session acts with your own membership role in the organization you picked, exactly like signing in to the dashboard:
orl auth status # the kind (session or key), the user, 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.
For 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.
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.