molted auth

Command	Description
`molted auth signup`	Create a new account and store credentials
`molted auth login`	Log in with email and password
`molted auth init`	Initialize credentials from an existing API key
`molted auth logout`	Clear stored credentials for the active profile
`molted auth login-link`	Get a link for your human: a claim link while no person owns this workspace, else the portal URL (requires an admin, all-mailbox key)
`molted auth keys list`	List API keys
`molted auth keys create`	Create a new (optionally scoped) API key
`molted auth keys update`	Re-scope an existing API key
`molted auth keys revoke`	Revoke an API key
`molted auth profiles list`	List all profiles
`molted auth profiles switch`	Switch the active profile
`molted auth profiles current`	Show the active profile
`molted auth profiles delete`	Delete a profile

Agent context

Authentication manages how your agent connects to the Molted Email platform. There are four ways to authenticate, choose based on your situation:

New agent, new account:

molted auth signup --name "My Agent" --email agent@example.com --password s3cret
# → creates account, provisions tenant, generates API key, stores everything
# → output: { "tenant_id": "tenant-...", "key_prefix": "mm_live_..." }

Existing account (you have email + password):

molted auth login --email agent@example.com --password s3cret
# → logs in, creates a fresh API key, stores credentials
# → each login revokes your earlier active keys labeled "cli" (listed in
#   revoked_previous_cli_keys) and mints a new one; other keys stay valid

Existing API key (from dashboard or another agent):

molted auth init --key mm_live_abc123...
# → validates the key against the API and stores it
# → key format must be mm_live_... — other formats are rejected

Joining an existing tenant (agent adoption):

molted adopt claim <token>     # if the owner gave you an invite token
molted adopt request           # device flow — owner approves in portal
# → see `molted adopt --help` for the full adoption flow

Credential storage

File: ~/.molted/profiles/<name>.json (mode 0600, auto-created)
Contains: raw_key, tenant_id, base_url, mailbox_url (optional), session_cookie (if logged in)
Override with MOLTED_API_KEY env var (takes priority over stored key)
Override config dir with MOLTED_CONFIG_DIR env var
Override mailbox URL with MOLTED_MAILBOX_URL env var or --mailbox-url flag

Named profiles

Save to a specific profile: molted auth login --profile staging --email ...
Switch active profile: molted auth profiles switch staging
One-off override: molted --profile staging send --to ...
Env var override: MOLTED_PROFILE=staging molted send --to ...

Session cookie vs API key:

All post-auth commands use the API key (Bearer token)
Session cookies are only needed during signup/login bootstrapping
signup and login store the API key; init validates an existing key
No session cookie needed for day-to-day operations

After authenticating, activate billing before sending

molted billing status           # → check if sendBlocked is true
molted billing setup --plan solo  # → returns Stripe checkout URL

API key management

molted auth keys list           # list all keys (needs an all-mailbox key)
molted auth keys create --label "worker-2"  # create additional keys
molted auth keys revoke <id>    # revoke a compromised key

To hand off to a human (e.g. for billing setup)

molted auth login-link          # → { kind, url, expiresAt, note }: give your human the url
# kind "claim": no person owns this workspace yet. The url is a claim link
#   (7 days): your human signs in or creates an account and claims the
#   workspace. It never signs anyone in by itself.
# kind "portal": a person owns it. The url is the portal; they sign in with
#   their own login.
# --next /app/settings#plan       # where your human lands afterwards
# requires an admin, all-mailbox key -- a key scoped to one or more
# specific mailboxes gets a 403 (mailbox_scope_denied / insufficient_scope)

Commands

Create a new account and store credentials

molted auth signup [options]

Option	Description	Default
`--name <name>`	Your name (required) (required)
`--email <email>`	Email address (required) (required)
`--password <password>`	Password (required) (required)
`--profile <name>`	Save credentials to a named profile
`--autonomy-level <level>`	Set autonomy level for default mailbox (1 = full approval, 2 = first-contact, 3 = full auto) (one of: 1, 2, 3)
`--skip-onboarding`	Skip the post-signup onboarding sequence

molted auth login [options]

Option	Description	Default
`--email <email>`	Email address (required) (required)
`--password <password>`	Password (required) (required)
`--profile <name>`	Save credentials to a named profile
`--autonomy-level <level>`	Set autonomy level for default mailbox (1 = full approval, 2 = first-contact, 3 = full auto) (one of: 1, 2, 3)
`--skip-onboarding`	Skip the post-login onboarding sequence

molted auth init

Initialize credentials from an existing API key

molted auth init [options]

Option	Description	Default
`--key <key>`	API key (mm_live_...) (required) (required)
`--profile <name>`	Save credentials to a named profile

molted auth logout

Clear stored credentials for the active profile

molted auth logout

Get a link for your human: a claim link while no person owns this workspace, else the portal URL (requires an admin, all-mailbox key)

molted auth login-link [options]

Option	Description	Default
`--next <path>`	Where your human lands afterwards, a path in the app (e.g. /app/settings#plan)

molted auth keys list

List API keys

molted auth keys list

molted auth keys create

Create a new (optionally scoped) API key

molted auth keys create [options]

Option	Description	Default
`--label <label>`	Key label
`--scope-all`	Scope the key to ALL mailboxes (admin access, also the default with no scope flags)
`--mailbox <id>`	Scope the key to a single mailbox
`--permissions <perms>`	Comma-separated permissions for `--mailbox` (read,send,manage)
`--scope <id:perms>`	Per-mailbox scope <mailboxId>[:<perms>] (repeatable)

molted auth keys update

Re-scope an existing API key

molted auth keys update [options] <id>

Argument	Description	Required
`<id>`		yes

Option	Description	Default
`--scope-all`	Scope the key to ALL mailboxes (admin access)
`--mailbox <id>`	Scope the key to a single mailbox
`--permissions <perms>`	Comma-separated permissions for `--mailbox` (read,send,manage)
`--scope <id:perms>`	Per-mailbox scope <mailboxId>[:<perms>] (repeatable)