Connecting the CLI - RELAI On-Prem

The relai CLI talks to your backend on port 8889. It can authenticate in two ways:

API key — works everywhere, including headless servers and CI. This is the default for on-prem deployments.
OAuth sign-in — each user signs in through the dashboard. It is off by default; see Optional: sign in with OAuth to turn it on.

Create an API key

Open the dashboard at http://localhost:5173 and sign in. Then create a key in one of these places:

Settings → Account → API keys for a key tied to your own user.
Settings → Workspace → API keys for a key shared by the workspace, such as one used in CI.

Copy the key when it is shown. Treat it like a password.

Configure the CLI

On the machine where you run relai:

relai setup --theme light --api-url http://<backend-host>:8889 --api-key <api-key>

Use http://localhost:8889 when the CLI runs on the same host as the Docker Compose stack. --theme accepts light or dark, and is required when setup runs without an interactive terminal. The URL and key are saved to ~/.relai/config.toml, so keep that file private.Setup also lists any prerequisite tools that are missing on this machine. Run relai setup --check to see that list again.

Confirm it worked

relai auth status

The output should read Authentication: API key. This only confirms the CLI has a key saved. To check that the backend accepts it:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Token <api-key>" \
  http://<backend-host>:8889/api/v1/agent-studio/agents/

200 means the key works. 401 means the key is wrong or was deleted.

Non-interactive setup

In CI or scripts, set the URL and key as environment variables rather than passing them on the command line:

export RELAI_API_URL="http://<backend-host>:8889"
export RELAI_API_KEY="<api-key>"
relai setup --theme light

relai setup saves both values to ~/.relai/config.toml, so later commands work without them. To keep the variables in every new shell, add the two export lines to your shell profile (~/.bashrc, ~/.zshrc, or equivalent). That file then holds the key in plain text, so keep it private; in CI, use your system’s secret store instead.

Rotating a key

Create a new key, run the relai setup command above again with it, then delete the old key from the same settings page in the dashboard. With OAuth turned on, users sign in to the CLI through the dashboard instead of copying an API key. The CLI prints a short code, the user approves it in the dashboard and picks a workspace, and the CLI keeps a session that renews itself.

OAuth tokens are stored only in the operating system’s credential store: Keychain on macOS, Credential Manager on Windows, or a Secret Service keyring on Linux. Headless Linux servers usually don’t have one, so keep using an API key there and in CI.

Before you start

Your backend and dashboard versions must include OAuth support. Ask RELAI which versions to use.
SERVER_BASE_URL and LANDING_PAGE_URL in .env must be the addresses your users’ browsers and CLI actually use. The backend uses them as the OAuth issuer and as the approval page location, and the CLI refuses to sign in when its --api-url doesn’t match the issuer exactly (scheme, host, and port).

Turn it on

Generate a signing key

Run this once, in a private directory. It needs OpenSSL and jq:

(umask 077; openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  | jq -Rsc '[{pem: ., issued_at: (now | todate)}]' > oidc-keys.json)

Generate it once and reuse the same key across restarts and upgrades, rather than creating a new one each time.

Update .env

In the CLI OAuth section of your .env, paste the contents of oidc-keys.json between the single quotes of IDP_OIDC_PRIVATE_KEYS, and set RELAI_OIDC_ENABLED="True":

RELAI_OIDC_ENABLED="True"
RELAI_OIDC_ISSUER="${SERVER_BASE_URL}"
LOGIN_REDIRECT_URL="${LANDING_PAGE_URL}"
IDP_OIDC_PRIVATE_KEYS='[{"pem":"-----BEGIN PRIVATE KEY-----\n...","issued_at":"..."}]'

Leave RELAI_OIDC_ISSUER and LOGIN_REDIRECT_URL as shown unless you need different values. .env now holds a private key, so restrict it with chmod 600 .env and delete oidc-keys.json once it’s pasted in.

Restart the backend

docker compose up -d --force-recreate init-commands app celery-worker
docker compose logs init-commands | grep OIDC

The log should show Created OIDC client relai-cli. (or Updated on later restarts). To confirm the backend is serving OAuth:

curl -s http://<backend-host>:8889/.well-known/openid-configuration

The response is JSON whose issuer matches SERVER_BASE_URL.

relai setup --api-url http://<backend-host>:8889

The CLI prints a dashboard link and a short code, and tries to open the link in your browser. Sign in to the dashboard if asked, approve the request, and choose a workspace. The code expires after five minutes. Confirm the session with:

relai auth status

The output shows Authentication: OAuth with your user, organization, and workspace. Once the URL is saved, run relai auth login to sign in again or switch workspaces, and relai auth logout to end the session.

​Sign in with an API key

​Non-interactive setup

​Rotating a key

​Optional: sign in with OAuth

​Before you start

​Turn it on

​Sign in from the CLI

Sign in with an API key

Non-interactive setup

Rotating a key

Optional: sign in with OAuth

Before you start

Turn it on

Sign in from the CLI