Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
CLI

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 login

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

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

The 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: Owner

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

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

SettingFlagEnvironmentStored / default
Credential--api-keyOPENRELAY_API_KEYkeyring / consented file
Organization--orgOPENRELAY_ORG_IDresolved from the credential
API base URL--api-urlOPENRELAY_API_URLhttps://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 logout

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

On this page