Ravi

Authentication

Overview

Ravi uses OAuth device-code flow for authentication. This works in any environment — terminal, headless VM, or CI — without needing a callback URL.

Login flow

ravi auth login
  1. The CLI requests a device code from the Ravi API
  2. A verification URL is displayed — open it in any browser
  3. Complete the OAuth flow in the browser
  4. The CLI polls for the token and stores it locally

On headless machines, copy-paste the verification URL to a browser on any device.

Encryption setup

On first login, you’ll be prompted to create a 6-digit PIN:

  1. Choose a PIN — enter and confirm a 6-digit numeric PIN
  2. Key derivation — the PIN + a server-stored salt produce encryption keys via Argon2id
  3. Public key upload — the derived public key is sent to the server
  4. Recovery key — saved to ~/.ravi/recovery-key.txt (back this up)

On subsequent logins, you enter your existing PIN (3 attempts) to unlock the stored keypair.

Token management

  • Access tokens expire after 1 hour
  • Automatic refresh — the CLI refreshes tokens transparently before expiry
  • No re-login needed — as long as the refresh token is valid, you stay authenticated
# Check current auth status
ravi auth status --json
{
  "authenticated": true,
  "email": "you@example.com",
  "has_encryption": true
}

Stored credentials

Authentication state is stored in ~/.ravi/ with 0600 permissions:

FileContents
auth.jsonAccess token, refresh token, encryption keypair
config.jsonActive Identity (UUID and name)
recovery-key.txtRecovery key for encryption (first login only)

Per-project Identity

Place a .ravi/config.json in any project directory to override the global Identity for that project:

{
  "identity_uuid": "uuid-here",
  "identity_name": "project-agent"
}

The CLI checks for a local config first, then falls back to ~/.ravi/config.json.

Logout

ravi auth logout

This clears stored tokens. Your encryption keys and Identity configuration remain intact.

OpenClaw authentication

The OpenClaw plugin uses the same auth flow:

openclaw ravi login

This runs the same device-code flow, sets up encryption, selects an Identity, and auto-configures the OpenClaw plugin. Credentials are stored in the same ~/.ravi/auth.json file, so the CLI and OpenClaw plugin share authentication state.

Next steps