Skip to main content

CLI Reference

The @spawnmail/cli package provides a command-line interface for SpawnMail.

Installation​

# Global install
bun add -g @spawnmail/cli

# Or use without installing
npx @spawnmail/cli <command>

Authentication​

# Store API key locally (~/.config/spawnmail/config.json)
spawnmail login --key fm_your_api_key

# Or use environment variable
export SPAWNMAIL_API_KEY=fm_your_api_key

Config resolution order:

  1. --key / --api flags (per-command override)
  2. SPAWNMAIL_API_KEY / SPAWNMAIL_API_URL environment variables
  3. ~/.config/spawnmail/config.json
info

The CLI defaults to http://localhost:8000 as the API URL. For the cloud service, run spawnmail login --key fm_... --api https://api.spawnmail.sh.

Commands​

spawnmail create​

Create a new disposable inbox.

# Human-friendly output
spawnmail create
# → abc123def456@spawnmail.sh

# With TTL and password
spawnmail create --ttl 300 --password secret123

# JSON output (for scripting)
spawnmail create --json
# { "id": "abc123def456", "address": "abc123def456@spawnmail.sh", ... }

spawnmail read <inbox-id>​

List emails in an inbox.

# Human-friendly
spawnmail read <inbox-id>
# → { from: "noreply@example.com", subject: "Verify your email" }

# With password
spawnmail read <inbox-id> --password secret123

# JSON output
spawnmail read <inbox-id> --json

spawnmail destroy <inbox-id>​

Delete an inbox and all its emails.

spawnmail destroy <inbox-id>
# → gone.

Shell Scripting Patterns​

Create and Parse ID​

INBOX_JSON=$(spawnmail create --json)
INBOX_ID=$(echo "$INBOX_JSON" | jq -r '.id')
INBOX_ADDR=$(echo "$INBOX_JSON" | jq -r '.address')
echo "Created inbox: $INBOX_ADDR"

Poll for Emails​

for i in $(seq 1 12); do
  EMAILS=$(spawnmail read "$INBOX_ID" --json)
  COUNT=$(echo "$EMAILS" | jq 'length')
  if [ "$COUNT" -gt 0 ]; then
    echo "Got $COUNT email(s)"
    break
  fi
  sleep 5
done

Extract OTP from Email​

EMAILS=$(spawnmail read "$INBOX_ID" --json)
OTP=$(echo "$EMAILS" | jq -r '.[0].body_text' | grep -oE '[0-9]{4,8}' | head -1)
echo "OTP: $OTP"
EMAILS=$(spawnmail read "$INBOX_ID" --json)
LINK=$(echo "$EMAILS" | jq -r '.[0].body_text' | grep -oE 'https?://[^ ]*verif[^ ]*' | head -1)
echo "Verify link: $LINK"

Custom API URL​

# All commands accept --api flag for self-hosted instances
spawnmail create --api http://localhost:8000
spawnmail read abc123 --api http://localhost:8000