CLI Reference

@molted/cli is the agent-facing command line for Molted. It wraps the API: it stores credentials, adds the Authorization header and your tenant ID to every request, and prints JSON.

npm install -g @molted/cli
molted --version

Every page in this section is generated from the CLI's own help text (molted <command> --help), so it matches the published package built from the same source. For a guided first run, see CLI Quickstart.

Global options

Global options go before the command (molted --profile work send ...).

Agent context

Molted Email is an agent-native email control plane. The molted CLI handles authentication, headers, and tenant ID injection automatically so you can interact with the API using simple commands instead of raw HTTP calls.

After install (npm install -g @molted/cli), the molted binary is available in your PATH. Verify with: molted --version

Quick start (3 steps)

molted auth signup --name "My Agent" --email agent@example.com --password <password>
# → credentials stored in ~/.molted/profiles/default.json automatically

molted billing setup --plan solo
# → returns { "url": "https://checkout.stripe.com/...", "plan": "solo" }
# → sends are blocked until billing is active (trial_not_activated)

molted send --to alice@example.com --template _default \
  --dedupe-key "hello-alice-1" --payload '{"subject":"Hello","html":"Hi!","text":"Hi!"}'
# → { "status": "queued", "requestId": "..." }

If you already have an API key (mm_live_...), skip signup

molted auth init --key mm_live_xxx

To join an existing tenant as a new agent

molted adopt claim <token>       # if you have an invite token (ma_inv_...)
molted adopt request             # device flow (owner approves in the portal)

Output format

• Success (exit 0): JSON to stdout
• Error (exit 1): JSON to stderr, { "error": "message", "detail"?: ... }
• Policy-blocked sends return exit 0 with "status": "blocked", so always check status
• molted doctor has its own exit codes (0 ready, 1 blocker found, 2 not fully verified)

• Credentials: ~/.molted/profiles/<profile>.json (auto-created, mode 0600)
• Config dir override: MOLTED_CONFIG_DIR env var
• API key override: MOLTED_API_KEY env var (with MOLTED_TENANT_ID also set, the credentials file is not read at all)
• Tenant override: MOLTED_TENANT_ID env var
• Profile override: --profile flag > MOLTED_PROFILE env var > active_profile file > "default"
• Base URL override: --base-url flag > MOLTED_BASE_URL env var > credentials file > https://api.molted.email
• Mailbox URL override: --mailbox-url flag > MOLTED_MAILBOX_URL env var > credentials file > base URL

Requests go to the mailbox URL, except auth signup, auth login, auth init, adopt claim and adopt request, which call the base URL.

Run molted <command> --help for detailed context on any command. Run molted --skill to print the full agent skill reference.
Full reference: https://molted.email/cli-skill.md

Commands