CircleInbox CLI

Email infrastructure for agents and developers. Manage inboxes, send email, store credentials, and orchestrate password resets — all from the command line.

Installation

npm install -g @circleinbox/cli

Or run directly:

npx @circleinbox/cli help

Quick Start

# 1. Login with your API key
circleinbox login --key ci_live_YOUR_KEY

# 2. Check connection
circleinbox status

# 3. List your domains
circleinbox domains list

# 4. Check inbox
circleinbox inbox check [email protected]

# 5. Send an email
circleinbox send --from [email protected] --to [email protected] --subject "Hello" --text "Hi there!"

Authentication

API keys are encrypted with AES-256-GCM and stored at ~/.circleinbox/credentials. On macOS, the encryption key is stored in the system keychain.

circleinbox login                     # Interactive prompt
circleinbox login --key ci_live_...   # Direct key
CIRCLEINBOX_API_KEY=ci_live_... circleinbox status  # Env var fallback
circleinbox logout                    # Remove credentials

Commands

General

| Command | Description | |---------|-------------| | login [--key <key>] | Store API key (encrypted) | | logout | Remove stored credentials | | status | Show connection status and org info | | version | Show CLI version | | help | Show all commands |

Domains

circleinbox domains list              # List all domains with DNS status
circleinbox dns check example.com     # Check DNS records for a domain

DNS check shows MX, SPF, DKIM, and DMARC status with required records for any missing entries.

Inboxes

circleinbox inbox list                          # List all mailboxes
circleinbox inbox create [email protected]      # Create a new mailbox
circleinbox inbox check [email protected]       # List emails (default: 20)
circleinbox inbox check [email protected] -l 50 # List 50 emails
circleinbox inbox read [email protected] 1      # Read email UID 1
circleinbox inbox delete [email protected]      # Delete mailbox (with confirmation)

Mailbox arguments accept either an email address or a mailbox UUID.

Send Email

# Basic send
circleinbox send --from [email protected] --to [email protected] \
  --subject "Hello" --text "Message body"

# With HTML
circleinbox send --from [email protected] --to [email protected] \
  --subject "Hello" --html "<p>Message body</p>"

# With idempotency key (prevents duplicate sends)
circleinbox send --from [email protected] --to [email protected] \
  --subject "Hello" --text "Body" --idempotency-key unique-123

# Pipe body from stdin
echo "Hello from pipe" | circleinbox send --from [email protected] \
  --to [email protected] --subject "Piped" --text -

Aliases

circleinbox alias list                                    # List all aliases
circleinbox alias list --domain example.com               # Filter by domain
circleinbox alias create [email protected] [email protected]  # Create alias
circleinbox alias update ALIAS_ID [email protected]    # Update destinations
circleinbox alias delete ALIAS_ID                         # Delete alias

Vault (Credentials)

Store and retrieve website login credentials, encrypted in MechVault.

# List credentials for a mailbox (no passwords shown)
circleinbox vault list [email protected]

# Store a credential (password auto-generated if not provided)
circleinbox vault store [email protected] \
  --service https://github.com \
  --username [email protected] \
  --notes "2FA enabled"

# Get credential with password
circleinbox vault get [email protected] a1b2c3d4e5f6

# Update credential
circleinbox vault update [email protected] a1b2c3d4e5f6 \
  --password "new-password" \
  --notes "Updated 2026-02-13"

# Delete credential
circleinbox vault delete [email protected] a1b2c3d4e5f6

Password Reset

Orchestrated password reset flow that polls for reset emails and extracts reset links.

# Generic flow (for any website)
# 1. Looks up credential  2. You trigger reset in browser
# 3. Polls inbox for email  4. Extracts reset links  5. Updates vault
circleinbox reset [email protected] a1b2c3d4e5f6

# ClearAuth direct API flow (no browser needed)
circleinbox reset [email protected] a1b2c3d4e5f6 --clearauth

# With pre-set new password
circleinbox reset [email protected] a1b2c3d4e5f6 --password "new-pass"

Provision

Full domain-to-mailbox provisioning in one command.

# Provision with defaults ([email protected])
circleinbox provision example.com

# Custom local part and display name
circleinbox provision example.com --local support --display "Support"

# Dry run (show what would happen)
circleinbox provision example.com --dry-run

Global Flags

| Flag | Description | |------|-------------| | --json | Output raw JSON (for piping to jq) | | --quiet | Suppress decorative output | | --api-url <url> | Override API base URL |

JSON output examples

# Pipe to jq for structured queries
circleinbox domains list --json | jq '.data[] | {domain, status}'
circleinbox inbox check [email protected] --json | jq '.data.emails[] | {uid, subject}'
circleinbox vault get [email protected] hash --json | jq '.data.password'

Environment Variables

| Variable | Description | |----------|-------------| | CIRCLEINBOX_API_KEY | API key fallback (if not logged in) |

Configuration

Config stored at ~/.circleinbox/config.json:

{
  "apiUrl": "https://circleinbox.com/api/v1",
  "outputFormat": "pretty"
}

Requirements

• Node.js 20+
• CircleInbox API key (ci_live_ prefix)

License

MIT