> ## Documentation Index
> Fetch the complete documentation index at: https://self-hosted-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting the CLI

> Authenticate the relai CLI against your self-hosted backend.

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](#optional-sign-in-with-oauth) to
  turn it on.

## Sign in with an API key

<Steps>
  <Step title="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.
  </Step>

  <Step title="Configure the CLI">
    On the machine where you run `relai`:

    ```sh theme={"system"}
    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.
  </Step>

  <Step title="Confirm it worked">
    ```sh theme={"system"}
    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:

    ```sh theme={"system"}
    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.
  </Step>
</Steps>

### Non-interactive setup

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

```sh theme={"system"}
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.

## Optional: sign in with OAuth

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.

<Note>
  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.
</Note>

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

<Steps>
  <Step title="Generate a signing key">
    Run this once, in a private directory. It needs OpenSSL and `jq`:

    ```sh theme={"system"}
    (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.
  </Step>

  <Step title="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"`:

    ```dotenv theme={"system"}
    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.
  </Step>

  <Step title="Restart the backend">
    ```sh theme={"system"}
    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:

    ```sh theme={"system"}
    curl -s http://<backend-host>:8889/.well-known/openid-configuration
    ```

    The response is JSON whose `issuer` matches `SERVER_BASE_URL`.
  </Step>
</Steps>

### Sign in from the CLI

```sh theme={"system"}
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:

```sh theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.