# CLI

Install and use the Robotomail command-line interface.

## Installation

Install the CLI globally via npm:

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

Or use npx to run without installing:

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


## Authentication

Save your API key directly, or sign up / log in to generate one. Credentials are stored in `~/.robotomail/config` (TOML format).

```shell
# Save an existing API key
robotomail auth token rm_your_key_here

# Or sign up for a new account
robotomail auth signup --email you@example.com --slug myagent

# Or log in to an existing account
robotomail auth login --email you@example.com

# Check current auth status
robotomail auth whoami
```


## Commands

### Auth

```shell
robotomail auth signup     # Create new account
robotomail auth login      # Log in and generate API key
robotomail auth token <key>  # Save API key directly
robotomail auth whoami     # Show current auth status
robotomail auth keys       # List all API keys
robotomail auth revoke <keyId>  # Revoke an API key
```

### Stats

```shell
robotomail stats           # Show account stats (mailboxes, usage, storage)
```

### Mailboxes

```shell
robotomail mailbox list                  # List mailboxes
robotomail mailbox create <address>     # Create a mailbox
robotomail mailbox delete <address>     # Delete a mailbox (by address)
robotomail mailbox pause <address>      # Pause a mailbox
robotomail mailbox resume <address>     # Resume a paused mailbox
```

### Messages

```shell
robotomail send \
  --from <mailbox> \
  --to recipient@example.com \
  --subject "Hello" \
  --body "Message body"

robotomail messages <mailbox>              # List messages
robotomail message <mailbox> <messageId>   # Read a single message
```

### Threads

```shell
robotomail threads <mailbox>                # List threads
robotomail thread <mailbox> <threadId>     # View thread with messages
```

### Domains

```shell
robotomail domain list                   # List domains
robotomail domain add <domain>          # Register a domain
robotomail domain verify <domain>       # Trigger DNS verification
robotomail domain remove <domain>       # Remove a domain
```

### Webhooks

```shell
robotomail webhook list                  # List webhooks
robotomail webhook add <url>            # Create a webhook
robotomail webhook remove <webhookId>   # Remove a webhook
```

### Listen (SSE)

```shell
robotomail listen                        # Stream all events in real time
robotomail listen --forward-to http://localhost:4000/hook  # Forward to local URL
robotomail listen --mailbox agent@robotomail.co            # Filter to one mailbox
robotomail listen --events message.received,message.bounced
robotomail listen --json                 # Output NDJSON for piping
```

Stream real-time events via SSE — like `stripe listen`. Use `--forward-to` to forward events to a local HTTP endpoint with HMAC-SHA256 signatures. Events: `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complaint`.

### Config

```shell
robotomail config show                   # Display current config
robotomail config path                   # Show config file path
robotomail config get <key>              # Get a config value
robotomail config set <key> <value>      # Set a config value
```


## Output format

By default, the CLI outputs human-readable tables. Use `--json` for machine-readable JSON output:

```shell
robotomail messages <mailbox> --json
```


---

Previous: [Claude Code channel](https://robotomail.com/docs/guides/claude-code-channel.md) | Next: [Changelog](https://robotomail.com/docs/changelog.md)