## Authentication

| Command | Description |
|---------|-------------|
| `ravi auth login` | Authenticate via browser OAuth flow |
| `ravi auth logout` | Clear stored credentials |
| `ravi auth status` | Show current authentication status |

```bash
ravi auth status
```

## Identity management

| Command | Description |
|---------|-------------|
| `ravi identity list` | List all Identities |
| `ravi identity create --name "X"` | Create a new Identity |
| `ravi identity use <uuid>` | Set the active Identity |

```bash
# Create and switch to a new Identity
ravi identity create --name "research-agent"
ravi identity use <identity-uuid>
```

## Identity info

| Command | Description |
|---------|-------------|
| `ravi get email` | Get the active Identity's email address |
| `ravi get phone` | Get the active Identity's phone number |

```bash
EMAIL=$(ravi get email | jq -r '.email')
PHONE=$(ravi get phone | jq -r '.phone_number')
```

## Inbox (grouped)

Messages grouped by conversation (SMS) or thread (email).

| Command | Description |
|---------|-------------|
| `ravi inbox email` | List email threads |
| `ravi inbox email <thread-id>` | View a specific email thread |
| `ravi inbox email --unread` | Email threads with unread messages |
| `ravi inbox sms` | List SMS conversations |
| `ravi inbox sms <conversation-id>` | View a specific SMS conversation |
| `ravi inbox sms --unread` | SMS conversations with unread messages |

```bash
# Get unread SMS previews
ravi inbox sms --unread | jq -r '.[].preview'

# Read a specific email thread
ravi inbox email <thread_id> | jq -r '.messages[].text_content'
```

## Messages (flat)

Individual messages without grouping.

| Command | Description |
|---------|-------------|
| `ravi message email` | List all email messages |
| `ravi message email <message-id>` | View a specific email message |
| `ravi message email --unread` | Unread email messages only |
| `ravi message sms` | List all SMS messages |
| `ravi message sms <message-id>` | View a specific SMS message |
| `ravi message sms --unread` | Unread SMS messages only |

## SMS sending

| Command | Description |
|---------|-------------|
| `ravi sms send` | Send an SMS from the active Identity's phone number |

**Send flags:**

| Flag | Required | Description |
|------|----------|-------------|
| `--to` | Yes | Recipient phone number in E.164 format (e.g. `+15551234567`) |
| `--body` | Yes | Message text (plain text only, max 1600 characters) |

```bash
# Send a one-time passcode via SMS
ravi sms send --to "+15551234567" --body "Your code is 482910"

# Notify a human approver from a setup script
ravi sms send \
  --to "${APPROVER_PHONE}" \
  --body "Agent workspace ${WORKSPACE_NAME} is ready at ${WORKSPACE_URL}"
```

:::note
`ravi sms send` uses the **active Identity's** provisioned phone number as the sender. Switch identities first with `ravi identity use`, or target one directly with `--identity <uuid>`, if you need to send from a specific agent's number.
:::

## Calls

| Command | Description |
|---------|-------------|
| `ravi call --to <e164>` | Place an outbound call from the active Identity's phone number |
| `ravi call list` | List calls |
| `ravi call transcript <call-id>` | Show a call's transcript |
| `ravi call hangup <call-id>` | Hang up an active call |

```bash
# Place a call and capture the call id
CALL_ID=$(ravi call --to "+15551234567" | jq -r '.uuid')

# Fetch the transcript once the call ends
ravi call transcript "$CALL_ID"
```

## Email sending

| Command | Description |
|---------|-------------|
| `ravi email compose` | Compose and send a new email |
| `ravi email reply <message-id>` | Reply to sender only |
| `ravi email reply-all <message-id>` | Reply to all recipients |
| `ravi email forward <message-id>` | Forward an email |

**Compose flags:**

| Flag | Required | Description |
|------|----------|-------------|
| `--to` | Yes | Recipient email address |
| `--subject` | Yes | Email subject line |
| `--body` | Yes | Email body (HTML supported) |
| `--cc` | No | CC recipients (comma-separated) |
| `--bcc` | No | BCC recipients (comma-separated) |
| `--attach` | No | File to attach (repeatable) |

```bash
ravi email compose \
  --to "user@example.com" \
  --subject "Report" \
  --body "<p>See attached.</p>" \
  --attach report.pdf
```

**Reply flags:** `--body` (required), `--cc`, `--bcc`, `--attach` (optional)

## Passwords

| Command | Description |
|---------|-------------|
| `ravi passwords list` | List all stored passwords |
| `ravi passwords get <uuid>` | Show a password entry |
| `ravi passwords create <domain>` | Create a new entry |
| `ravi passwords update <uuid>` | Update a password entry |
| `ravi passwords delete <uuid>` | Delete a password entry |
| `ravi passwords generate` | Generate a random password without storing |

**Create flags:** `--username`, `--password`, `--generate`, `--length` (default: 16), `--no-special`, `--no-digits`, `--exclude-chars`, `--notes`

```bash
# Auto-generate a password for a domain
ravi passwords create github.com --username "agent@in.ravi.app"

# Generate without storing
ravi passwords generate --length 32
```

## Secrets

| Command | Description |
|---------|-------------|
| `ravi secrets set <key> <value>` | Store a secret (creates or updates) |
| `ravi secrets get <key>` | Retrieve a secret by key |
| `ravi secrets list` | List all secret keys |
| `ravi secrets delete <uuid>` | Delete a secret by UUID |

```bash
ravi secrets set OPENAI_API_KEY "sk-abc123..."
ravi secrets get OPENAI_API_KEY | jq -r '.value'
ravi secrets list | jq -r '.[].key'
```

## Feedback

| Command | Description |
|---------|-------------|
| `ravi feedback "<message>"` | Send feedback to the Ravi team |

```bash
ravi feedback "Love the CLI, but would like custom domains"
```

## Global flags

| Flag | Description |
|------|-------------|
| `--human` | Output in human-readable format. JSON is the default. |
| `--identity <uuid>` | Target a specific identity for per-identity calls (messages, contacts, passwords, secrets, calls, events). When omitted, the active identity key scopes the request. |
| `--help` | Show help for any command |
| `--version` | Show version information |

The API key is an **auth fence** — it defines what you're allowed to touch. The *caller* chooses the identity. A management key with `--identity <uuid>` targets one identity; an identity-scoped key is already fenced to its identity, and `--identity` must match it.