Authentication

Set up authentication for the Riven CLI, CI pipelines, and multi-org workflows.

Overview

The Riven CLI supports multiple authentication methods depending on your environment. For local development, use the browser-based login flow. For CI/CD pipelines, use a RIVEN_TOKEN environment variable.

The primary authentication method for local development. Running riven auth login generates a random handshake code, opens your browser, and polls the dashboard until the token is ready:

Terminal

bash

riven auth login

Expected output

text

Opening browser...
https://dashboard.riven-ai.dev/auth/cli?code=<random>
Waiting for authentication...
✓ Logged in as you@example.com (org: riven-ai)
Credentials saved to ~/.config/riven/credentials.json

The browser navigates to dashboard.riven-ai.dev/auth/cli?code=<random>. If you are not already signed in, the page prompts you to log in. Once authenticated, the dashboard mints a long-lived CLI API key (via /api/auth/cli-token), posts it to /api/auth/cli-exchange under the handshake code, and the CLI — which is polling /api/auth/cli-exchange?code=<random> every 2 seconds — receives the token and stores it locally.

Verify Your Session

Check your current authentication status at any time:

Terminal

bash

riven auth status

Expected output

text

Authenticated as: you@example.com
Organization:     riven-ai
Token expires:    2026-03-22T04:00:00Z

Log Out

To clear your stored credentials:

Terminal

bash

riven auth logout

CI/CD Token

For non-interactive environments like CI/CD pipelines, set the RIVEN_TOKEN environment variable. This bypasses the browser login flow entirely.

Generate a token from the Riven dashboard under Settings > API Keys, or use the CLI:

Terminal

bash

riven auth token --scope ci --expires 90d

Expected output

text

Token created successfully.
RIVEN_TOKEN=rt_ci_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Expires: 2026-06-19T00:00:00Z

Then set it in your CI environment:

.github/workflows/deploy.yml

yaml

env:
  RIVEN_TOKEN: ${{ secrets.RIVEN_TOKEN }}

GitLab CI

bash

export RIVEN_TOKEN=$RIVEN_TOKEN
riven deploy

Token Storage

Credentials from riven auth login are stored at:

text

~/.config/riven/credentials.json

The file contains the JWT token, your user ID, organization ID, and expiration timestamp. The CLI refreshes the token automatically when it is close to expiring.

Never share or commit your credentials file. It is excluded from git by default, but make sure ~/.config/riven/ is not synced to cloud storage.

Token Resolution Order

When the CLI needs to authenticate, it checks for credentials in this order:

CLI flag — --token <value> passed directly to the command.
Environment variable — RIVEN_TOKEN set in the current shell.
Credentials file — ~/.config/riven/credentials.json from a previous riven auth login.
Project config — riven.config.ts with an inline token (not recommended).

The first source that provides a valid token wins. This lets you override credentials per-command or per-environment without changing your global config.

Multi-Org Support

If you belong to multiple organizations, you can switch between them:

Terminal

bash

# List your organizations
riven auth orgs
 
# Switch to a different org
riven auth login --org-id other-org

Expected output

text

Available organizations:
  riven-ai        (current)
  other-org
  staging-org
 
Switching to other-org...
✓ Logged in as you@example.com (org: other-org)

You can also set RIVEN_ORG_ID in your environment to target a specific org without re-authenticating:

Terminal

bash

RIVEN_ORG_ID=staging-org riven deploy

This is useful in CI pipelines where you deploy to multiple orgs from the same workflow.

PreviousConfiguration NextDev Center Overview