CLI Quickstart

1. Sign up

npx @molted/cli auth signup \
  --name "My Agent" \
  --email agent@yourapp.com \
  --password your-password

This creates your account and saves credentials to ~/.molted/credentials.json. All future commands authenticate automatically.

After signup, the CLI runs a brief onboarding sequence -- it fetches your default mailbox, optionally sets an autonomy level, and prints safety hints and next steps. To skip this and get a minimal JSON response (useful in scripted agent provisioning):

npx @molted/cli auth signup \
  --name "My Agent" \
  --email agent@yourapp.com \
  --password your-password \
  --skip-onboarding

--skip-onboarding is also available on auth login.

Already have an API key from the dashboard? Initialize the CLI directly:

npx @molted/cli auth init --key mm_live_your_key_here

2. Activate billing

Sends are blocked on trial accounts. Activate billing to unlock sending.

Free plan (no credit card required, 100 emails/month):

npx @molted/cli billing activate-free

Paid plan (starts a 14-day free trial):

npx @molted/cli billing setup --plan starter

Open the returned checkout URL to complete payment. See Billing & Plans for plan details.

3. Add a sending domain

npx @molted/cli domains add yourapp.com

You'll get back a domain ID and DNS records (DKIM, SPF, DMARC) to add at your DNS provider. After adding them, verify using the domain ID from the add response:

npx @molted/cli domains verify <domain-id>

4. Send your first email

npx @molted/cli send \
  --to recipient@example.com \
  --subject "Hello" \
  --body "First email from the CLI!"

The --to flag must be a valid email address (e.g. recipient@example.com). Invalid formats like bare usernames or missing domains are rejected by the server with a 400 Bad Request error.

The --subject and --body flags are shorthand for sending with the _default template. For HTML email, use --html instead of --body. For templates with custom payloads, use --template and --payload:

npx @molted/cli send \
  --to recipient@example.com \
  --template my-template \
  --dedupe-key "hello-1" \
  --payload '{"subject": "Hello", "firstName": "Ada"}'

A successful response:

{
  "requestId": "req_abc123",
  "status": "queued"
}

5. Check delivery

npx @molted/cli trace req_abc123

This shows the full request lifecycle: policy checks, provider selection, and delivery status.

Using the CLI without npx

If you prefer, install globally:

npm install -g @molted/cli

Then use molted directly instead of npx @molted/cli:

molted send --to recipient@example.com --template _default ...

Updating

molted update

When a newer version is available, molted update installs it and shows a changelog summary of what changed between your old version and the new one:

{
  "status": "updated",
  "from": "1.13.0",
  "to": "1.16.0",
  "changelog": [
    {
      "version": "1.16.0",
      "date": "2026-04-02",
      "changes": [
        "Add mailbox delete, clone, and stats commands",
        "Add --payload flag to send simulate for policy testing"
      ]
    }
  ],
  "changelogUrl": "https://molted.email/changelog",
  "hint": "Updated successfully. Run `molted --version` to verify."
}

In interactive terminals, a human-readable summary is also printed to stderr so you can see what changed at a glance.

Next steps

• Sending Email -- templates, payloads, and deduplication
• Domains -- DNS setup and verification
• Policy Simulation -- simulate sends before going live (molted send simulate)
• Full command reference -- all CLI commands and flags