Ravi

Installation

Install with Homebrew

The fastest way to install the Ravi CLI on macOS or Linux:

brew install ravi-hq/tap/ravi

Or in one line:

brew install ravi-hq/tap/ravi

To update later:

brew update && brew upgrade ravi

Pre-built binaries

Download the latest release for your platform from the GitHub releases page. Binaries are available for:

  • macOS (Apple Silicon and Intel)
  • Linux (amd64 and arm64)

Build from source

Requires Go 1.21+:

git clone https://github.com/ravi-hq/cli.git
cd cli
make build API_URL=https://ravi.app

The built binary will be at ./ravi. Move it to a directory on your $PATH.

Verify installation

ravi --version

Sign up

If you don’t have a Ravi account yet, sign up at ravi.app.

Authenticate

Log in with the CLI:

ravi auth login

This opens your browser for OAuth authentication. After completing the browser flow, the CLI stores your credentials at ~/.ravi/auth.json with secure file permissions.

:::note[Zero-knowledge encryption] First-time users will be prompted to create a 6-digit encryption PIN. This PIN derives the encryption keys for your credential vault using Argon2id key derivation — the server never sees your PIN, and your credentials never leave your machine unencrypted. A server-side breach exposes only ciphertext.

Back up the recovery key written to ~/.ravi/recovery-key.txt during setup — it is the only way to recover your vault if you forget your PIN. :::

Verify authentication

ravi auth status --json

Non-interactive & CI setup

The interactive browser flow works great for local development. For agents running inside git worktrees, Docker containers, GitHub Actions, or any headless environment, use the RAVI_ACCESS_TOKEN environment variable instead.

Step 1: authenticate once, interactively, on a machine with a browser:

ravi auth login

Step 2: extract your access token:

cat ~/.ravi/auth.json | jq -r '.access_token'

Step 3: inject it at runtime via environment variable:

export RAVI_ACCESS_TOKEN=<your-token>
ravi get email --json   # no browser required

When RAVI_ACCESS_TOKEN is set, the CLI skips the file-based auth lookup entirely and uses the token directly.

GitHub Actions example:

- name: Run agent
  env:
    RAVI_ACCESS_TOKEN: ${{ secrets.RAVI_ACCESS_TOKEN }}
  run: |
    EMAIL=$(ravi get email --json | jq -r '.email')
    echo "Agent email: $EMAIL"

Docker example:

# Dockerfile — no ravi auth login needed at build time
FROM ubuntu:24.04
RUN curl -fsSL https://ravi.app/install.sh | sh
ENTRYPOINT ["my-agent"]
# At launch, inject the token via env
docker run -e RAVI_ACCESS_TOKEN="$RAVI_ACCESS_TOKEN" my-agent-image

Tokens expire after ~1 hour. For long-running processes, refresh the token periodically:

# Refresh and export the new token
NEW_TOKEN=$(ravi auth refresh --json | jq -r '.access_token')
export RAVI_ACCESS_TOKEN="$NEW_TOKEN"

See Authentication for full details on token refresh and error handling, and Production Patterns for multi-process token injection.

Your first Identity

Once authenticated, create your first agent Identity:

ravi identity create --name "my-agent" --json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-agent",
  "inbox": "my-agent@in.ravi.app",
  "phone": "+15559876543"
}

Your agent now has a real email address and phone number — ready to receive verification codes and send messages. No configuration required.

# Confirm the Identity is active
ravi get email --json
# → {"email": "my-agent@in.ravi.app"}

Next steps