npm package: @robotomail/cli
Description: CLI for Robotomail — email infrastructure for AI agents
Latest version: 0.1.8

# @robotomail/cli

CLI for [Robotomail](https://robotomail.com) — email infrastructure for AI agents.

## Install

```bash
npm install -g @robotomail/cli
```

Or run directly:

```bash
npx @robotomail/cli --help
```

## Quick Start

```bash
# Sign up — creates your account and default mailbox (myagent@robotomail.co)
robotomail auth signup --email you@example.com --slug myagent

# Or save an existing API key
robotomail auth token <your-api-key>

# Send an email (your mailbox was created at signup)
robotomail send --from myagent@robotomail.co --to user@example.com \
  --subject "Hello" --body "Hi from my agent"

# List incoming messages
robotomail messages myagent@robotomail.co

# Set up a webhook for inbound email
robotomail webhook add https://myapp.com/webhook --events message.received
```

## Commands

### auth

```bash
robotomail auth signup --email <email> --slug <slug> [--password <pw>] [--name <name>]
robotomail auth login --email <email> [--password <pw>]
robotomail auth token <key>              # save an API key directly
robotomail auth keys                     # list API keys
robotomail auth revoke <keyId>           # revoke an API key
robotomail auth whoami                   # show current auth status
```

### mailbox

```bash
robotomail mailbox create <address> [--domain <domainId>] [--name <displayName>]
robotomail mailbox list
robotomail mailbox delete <address>
robotomail mailbox pause <address>
robotomail mailbox resume <address>
```

### send

```bash
robotomail send --from <mailbox> --to <recipients> --subject <subject> --body <body> \
  [--html <html>] [--reply-to <messageId>]
```

### messages / message

```bash
robotomail messages <mailbox> [--direction INBOUND|OUTBOUND] [--since <date>] [--json]
robotomail message <mailbox> <messageId>
```

### threads / thread

```bash
robotomail threads <mailbox>
robotomail thread <mailbox> <threadId>
```

### domain

```bash
robotomail domain add <domain>
robotomail domain list
robotomail domain verify <domain>
robotomail domain remove <domain>
```

### webhook

```bash
robotomail webhook add <url> [--mailbox <address>] [--events <events>]
robotomail webhook list
robotomail webhook remove <webhookId>
```

Default events: `message.received`. Available events: `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complaint`.

### listen

```bash
robotomail listen [--forward-to <url>] [--mailbox <address>] [--events <list>] [--json]
```

Stream real-time events via SSE. Use `--forward-to` to forward events to a local URL (like `stripe listen`).

Available events: `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complaint`.

Options:
- `--forward-to <url>` — Forward events to a local HTTP endpoint with HMAC signature
- `--mailbox <address>` — Filter to a specific mailbox
- `--events <list>` — Comma-separated event types to subscribe to
- `--json` — Output NDJSON (one JSON object per line) for piping

### stats

```bash
robotomail stats
```

### config

```bash
robotomail config show                   # show current config
robotomail config path                   # show config file location
robotomail config get <key>              # e.g. auth.api_key, defaults.domain
robotomail config set <key> <value>      # e.g. defaults.base_url
```

Config is stored at `~/.robotomail/config` in TOML format.

## Configuration

The CLI stores its config at `~/.robotomail/config`:

```toml
[auth]
api_key = "rm_live_..."
slug = "myagent"

[defaults]
base_url = "https://api.robotomail.com"
domain = "robotomail.co"
```

## License

MIT