Ravi

CLI Overview

What is the Ravi CLI?

The Ravi CLI (ravi) is a Go command-line client that gives AI agents programmatic access to their Identity — email, phone, credential vault, and 2FA. It's designed to be used by both humans and AI agents.

Installation

brew install ravi-hq/tap/ravi

See Installation for more options.

Design principles

JSON-first output

All commands support the --json flag. JSON output is stable and designed for programmatic parsing by AI agents. Human-readable output is for interactive use only.

# For agents — structured, parseable
ravi inbox email --unread --json | jq -r '.[0].subject'

# For humans — formatted, readable
ravi inbox email --unread

Client-side encryption

The CLI handles all encryption and decryption locally. When you store a password, it's encrypted before leaving your machine. When you retrieve one, it's decrypted after arriving. The server never sees plaintext credentials.

Transparent token management

Access tokens refresh automatically. The CLI detects token expiry and refreshes before making the request. If a request returns 401, it retries once after refreshing. You never need to manually manage tokens.

Identity scoping

Every API request is scoped to the active Identity via the X-Ravi-Identity header. Switch Identities with ravi identity use <name> and all subsequent commands operate against that Identity.

Configuration

Configuration is stored in ~/.ravi/ with secure file permissions (0600):

File Contents
auth.json Access token, refresh token, user email, encryption keypair
config.json Active Identity UUID and name

Per-project override

A .ravi/config.json in the current working directory overrides the global config. This allows different projects to use different Identities automatically.

Environment variables

The CLI respects two environment variable overrides. Neither is required for normal use, but both are important for container and multi-agent deployments:

Variable Description
RAVI_CONFIG_DIR Override the config directory (default: ~/.ravi). Point this at a per-process directory to isolate Identity state between parallel agents — the preferred alternative to ravi identity use in concurrent processes.
RAVI_ACCESS_TOKEN Override the Bearer access token read from auth.json. Useful in containers and CI where ~/.ravi/auth.json may not exist: extract the token at launch time on a machine with a browser, pass it as a secret, and inject it here.

RAVI_CONFIG_DIR — parallel agent isolation

# Harness: set up one config dir per worker at dispatch time
mkdir -p /workspace/agent-1/.ravi
echo '{"identity_uuid":"<uuid-1>"}' > /workspace/agent-1/.ravi/config.json

# Worker process: every ravi call targets agent-1's Identity — no global state mutation
RAVI_CONFIG_DIR=/workspace/agent-1/.ravi ravi get email --json
RAVI_CONFIG_DIR=/workspace/agent-1/.ravi ravi inbox sms --unread --json

When set, RAVI_CONFIG_DIR takes precedence over the default ~/.ravi directory and over any .ravi/config.json found in the current working directory. This makes it the safest isolation mechanism for parallel processes.

For a complete harness integration example, see Harness Integration.

RAVI_ACCESS_TOKEN — container and CI auth injection

The device-code login flow requires browser access once. For environments that run headlessly from the start (Docker containers, GitHub Actions, serverless), extract the token on a machine with a browser and inject it:

# On a machine with a browser — run once
ravi auth login
cat ~/.ravi/auth.json | jq -r '.access_token'
# → eyJhbGci... (copy this value)

# In your CI secret store or Docker run command:
docker run -e RAVI_ACCESS_TOKEN="eyJhbGci..." my-agent

# In a GitHub Actions workflow:
- name: Run agent
  env:
    RAVI_ACCESS_TOKEN: ${{ secrets.RAVI_ACCESS_TOKEN }}
  run: ./agent.sh

Token expiry: Access tokens expire after 1 hour. For long-running containers, pass the full auth.json content and mount it at ~/.ravi/auth.json so the CLI can refresh automatically. RAVI_ACCESS_TOKEN is best for short-lived jobs; file-based auth is better for daemons.

Command groups

Group Purpose
ravi auth Login, logout, check status
ravi identity Create, list, switch Identities
ravi get Get email address, phone number
ravi inbox Read SMS and email (grouped by conversation/thread)
ravi message Read individual messages (flat list)
ravi email Compose, reply, reply-all
ravi passwords Website credential CRUD
ravi secrets Key-value secret CRUD
ravi feedback Send feedback to the Ravi team

Global flags

Flag Description
--json Output in JSON format (recommended for agents)
--help Show help for any command
--version Show version information

Next steps