CLI reference

LiteMX CLI

Manage domains, mailboxes, messages, drafts, tokens, and MCP access from the terminal.

Install

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

install.sh

npm install -g litemx
litemx --help

# or run without installing
npx litemx --help

Contributors should keep using pnpm inside the LiteMX monorepo.

contributor.sh

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

Authenticate

API, CLI, and MCP use LiteMX-owned tokens. Clerk is only for future human dashboard auth. Use the founder admin token for operator setup, then create scoped mailbox tokens for agents or scripts.

auth.sh

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.

Domain Setup

`domains register` is DNS-plan-first by default. It creates LiteMX records and returns the records to add at the current DNS provider. Cloudflare commands are optional provider/debug commands only.

domains.sh

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.

vercel-dns.sh

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

Mailboxes are storage and access boundaries. Aliases and catchalls route addresses into an active mailbox. Disabled mailboxes retain history but no longer accept routing or outbound access.

routing.sh

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

messages.sh

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>

drafts.sh

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> --body "Thanks, this is a LiteMX test reply."

Core Options

Option	Use
`--json`	Print raw JSON output for scripts and agents.
`--mailbox`	Target a mailbox by address or accepted identifier.
`--domain`	Filter aliases, mailboxes, or setup commands to one domain.
`--ingestion-source provider`	Require real provider-ingested mail for smoke and wait checks.
`--include-inbound-mx`	Include the root inbound MX when publishing DNS records.
`--skip-cloudflare`	Skip optional legacy Cloudflare diagnostics in doctor-style checks.

JSON Output

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

json.sh

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.

tokens.sh

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>

mcp.sh

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.

Plan	Mailbox/day	Account/day	Account/month	Recipients/message
Free	100	100	500	10
Starter	300	300	3,000	10
Scale	1,000	1,000	15,000	10

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

real-smoke.sh

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