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