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 starts a local server and opens your browser to complete OAuth sign-in:

Terminal

bash

riven auth login

Expected output

text

Starting local auth server on port 9876...
Opening browser for authentication...
✓ Logged in as [email protected] (org: riven-ai)
Credentials saved to ~/.config/riven/credentials.json

The browser navigates to app.riven-ai.dev/auth/cli?port=9876, where you sign in with your Riven account. Once authenticated, a platform JWT is issued and sent back to the local server.

Verify Your Session

Check your current authentication status at any time:

Terminal

bash

riven auth status

Expected output

text

Authenticated as: [email protected]
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 [email protected] (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