LiteMX CLI

Install

Install the public CLI with npm, or run it once with npx. LiteMX requires Node.js 20 or newer.

npm install -g litemx
litemx --help

# or run without installing
npx litemx --help

The address and forwarding commands require litemx@0.1.1 or newer.

Contributors should keep using pnpm inside the LiteMX monorepo.

pnpm install
pnpm cli:build
node apps/cli/dist/src/index.js --help

Authenticate

Clerk handles human dashboard sign-in. API, CLI, and MCP use separate LiteMX-owned tokens. Use the founder admin token for operator setup, then create scoped mailbox tokens for agents or scripts.

litemx config set \
  --api-url https://litemx-api-worker.litemx.workers.dev \
  --token <founder-admin-token>
litemx login --token <founder-admin-token>
litemx auth status

Configure

The CLI reads its configured API URL and bearer token, and most commands also support `--json` for scriptable output. Do not commit local tokens or cloud provider credentials.

• `LITEMX_API_URL` can point at the deployed Worker or local API.
• `LITEMX_TOKEN` can provide a bearer token for automation.
• `VERCEL_API_TOKEN` or `VERCEL_TOKEN` is used only for Vercel DNS publishing.

Create An Address

`addresses create` is the shortest setup path. It creates the domain and address, adds the forwarding destination, configures the mailbox binding, provisions the mail providers, and returns the DNS plan.

litemx addresses create support@project.dev --forward-to owner@example.com
litemx domains dns-plan project.dev
litemx domains verify project.dev --timeout 120 --interval 5

Forwarding starts only after the destination is verified. Private founder builds can auto-verify an exact server-allowlisted address; every other destination remains pending until a one-time challenge is delivered and submitted.

litemx forwarding-destinations list
litemx mailboxes forwarding support@project.dev

# after the verification challenge arrives
litemx forwarding-destinations verify <destination-id> --token <one-time-token>
litemx mailboxes forwarding support@project.dev --destination <destination-id> --enable

Once forwarding is enabled, incoming mail arrives in the verified destination inbox. Reply in Gmail, Thunderbird, Fastmail, or the client you already use; LiteMX relays the response from the custom-domain address without exposing the destination to the correspondent. See the existing-inbox guide for security details and current private-build limitations.

Domain Setup

Use the address workflow above for normal setup. `domains register` remains available as a lower-level, DNS-plan-first command for operators who want to configure domain and mailbox primitives separately. Cloudflare commands are optional provider/debug commands only.

litemx domains register project.dev --mailbox ops --alias hello --display-name Ops --plan
litemx domains register project.dev --mailbox ops --alias hello --display-name Ops
litemx domains dns-plan project.dev
litemx domains verify project.dev

For Vercel DNS, the CLI can publish supported DNS records. It skips the root inbound MX by default so live mail is not redirected until the SES inbound bridge is ready.

export VERCEL_API_TOKEN=<vercel-token>
litemx domains dns-plan project.dev --publish --confirm-publish --dns-provider vercel
litemx domains dns-plan project.dev --publish --confirm-publish --dns-provider vercel --include-inbound-mx

Mailboxes And Mail

Addresses are the simple setup concept. Underneath, mailboxes are storage and access boundaries; aliases and catchalls route addresses into an active mailbox. These lower-level commands remain useful for automation and debugging.

litemx mailboxes create ops@project.dev
litemx aliases create hello@project.dev --to ops@project.dev
litemx catchall set project.dev ops@project.dev
litemx mailboxes read ops@project.dev

litemx messages list --mailbox ops@project.dev --limit 10
litemx messages search --mailbox ops@project.dev --query invoice
litemx messages wait --mailbox ops@project.dev --direction inbound --ingestion-source provider --query "unique subject"
litemx messages read <message-id>

litemx drafts create --mailbox ops@project.dev --to customer@example.com --subject "Hello" --body-file reply.txt
litemx drafts create --thread <thread-id> --body-file reply.txt
litemx drafts send <draft-id>
litemx threads reply <thread-id> --text "Thanks, this is a LiteMX test reply."

Core Options

JSON Output

Use JSON output when wiring LiteMX into scripts or automation. Human output is optimized for operators; JSON output preserves response fields.

litemx --json domains status project.dev
litemx --json messages read <message-id>
litemx --json audit list --mailbox ops@project.dev --limit 25

Agent Use

Tokens separate read, search, draft, and send access. Give agents the narrowest mailbox and action scopes that satisfy the job. Send access requires `email:send` and still passes provider readiness, send-limit, and policy checks.

litemx tokens create --name ops-agent --mailbox ops@project.dev --scopes messages:read,messages:search,drafts:write
litemx tokens list --limit 25
litemx tokens revoke <token-id>

litemx mcp info
litemx mcp test
litemx agent-skill print

Readiness And Limits

Real receiving requires MX delivery into the selected provider and raw MIME delivery into LiteMX. Real sending requires sender-domain verification, DKIM, explicit send scope, plan limits, and provider production approval.

Use the real smoke command after DNS records are published and the selected mail provider reports both receive and send readiness for the domain.

LITEMX_SMOKE_DOMAIN=project.dev \
LITEMX_SMOKE_MAILBOX=ops@project.dev \
LITEMX_SMOKE_ALIAS=hello@project.dev \
LITEMX_REQUIRE_REAL_EMAIL=1 \
LITEMX_REAL_INBOUND_QUERY="unique subject" \
LITEMX_REAL_SEND_TO=you@example.com \
pnpm manual:real-cli-smoke