CLI Overview — Ravi Docs

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.

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

Command Reference — full command listing with examples
Quick Start — get started with the CLI