# LiteMX CLI The LiteMX CLI is the terminal-first interface for domains, DNS setup, mailboxes, aliases, messages, drafts, replies, tokens, MCP access, retention, and audit logs. Human-friendly route: https://litemx.com/docs/cli ## Install ```sh pnpm cli:build node apps/cli/dist/src/index.js auth status ``` ## Auth And Config ```sh node apps/cli/dist/src/index.js config set \ --api-url https://litemx-api-worker.litemx.workers.dev \ --token node apps/cli/dist/src/index.js login --token node apps/cli/dist/src/index.js auth status ``` API, CLI, and MCP use LiteMX-owned scoped tokens. Clerk is only for future human dashboard auth. Useful environment variables: - `LITEMX_API_URL`: API Worker URL. - `LITEMX_TOKEN`: bearer token for automation. - `VERCEL_API_TOKEN` or `VERCEL_TOKEN`: Vercel DNS publishing token. ## Domain Setup ```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 litemx domains smoke project.dev --mailbox ops --inbound-query "unique subject" --to founder@example.com ``` `domains register` is DNS-plan-first by default. It creates the LiteMX domain, mailbox, alias, and catchall records, then returns the DNS setup plan for the domain's current DNS provider. It does not create a Cloudflare zone unless explicit Cloudflare provider/debug commands are used. `domains dns-plan` prints provider-agnostic records: inbound MX, ownership verification, DKIM CNAMEs, SPF, DMARC guidance, and bounce/MAIL FROM records. For AWS SES domains with configured provider state, it returns concrete SES records. Missing provider values are marked pending instead of faked. `domains verify` reads provider-agnostic readiness evidence: DNS records present, inbound route/receipt active, outbound sender/domain verified, and DKIM active. ## Vercel DNS Publishing ```sh export VERCEL_API_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 ``` The Vercel publisher lists existing records, skips exact matches, refuses conflicting same-name/type records, and supports `CNAME`, `MX`, and `TXT`. It skips the root inbound MX by default so live mail is not redirected before the inbound bridge is ready. Add `--include-inbound-mx` only when the domain should route inbound mail to LiteMX. ## Optional Cloudflare Commands Cloudflare commands are optional provider/debug commands, not the default onboarding path: ```sh litemx domains cloudflare-account litemx domains cloudflare-zone project.dev --cloudflare-account-id --run --confirm-create-zone --record litemx domains cloudflare-setup project.dev --run ``` Use them only when explicitly testing the legacy Cloudflare path or when a domain already uses Cloudflare DNS and that provider path is intentionally selected. `domains doctor --skip-cloudflare` skips optional Cloudflare diagnostics. ## Mailboxes And Mail ```sh litemx mailboxes create ops@project.dev litemx mailboxes read ops@project.dev litemx mailboxes delete old@project.dev litemx aliases create hello@project.dev --to ops@project.dev litemx aliases list --domain project.dev litemx aliases delete old-alias@project.dev litemx catchall set project.dev ops@project.dev ``` `mailboxes delete` soft-disables a mailbox. Existing messages and audit history remain, but inbound/outbound access is disabled. Recreating the same mailbox reactivates the existing row. ```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 litemx threads list --mailbox ops@project.dev --limit 10 litemx threads read ``` `messages wait --ingestion-source provider` is the right shape for real receive smoke tests. Simulated inbound remains a regression tool. ## Drafts And Sending ```sh litemx drafts create --mailbox ops@project.dev --to customer@example.com --subject "Hello" --body-file reply.txt litemx drafts create --thread --body-file reply.txt litemx drafts send litemx threads reply --body "Thanks, this is a LiteMX test reply." litemx send --from ops@project.dev --to customer@example.com --subject "Hello" --text "Thanks for writing." ``` Real sending requires provider-agnostic domain readiness, explicit send scope when using scoped tokens, plan limits, and provider approval. AWS SES production access is currently the blocker for arbitrary public outbound delivery. ## JSON Output ```sh litemx --json domains status project.dev litemx --json messages read litemx --json audit list --mailbox ops@project.dev --limit 25 ``` Use `--json` for scripts and agents. Human output is optimized for operators; JSON output preserves response fields. ## Tokens, MCP, Audit, And Retention ```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 litemx mcp info litemx mcp test litemx agent-skill print litemx audit list --mailbox ops@project.dev --action message.read --resource-type message --limit 25 litemx retention run ``` Read, draft, and send access are separate. A token that can read or search messages cannot create drafts or send unless it has the relevant scopes. `send_draft` and CLI send commands require `email:send`. ## Plan Send Limits | Plan | Per mailbox/day | Per account/day | Per account/month | Recipients/message | | --- | ---: | ---: | ---: | ---: | | Free | 100 | 100 | 500 | 10 | | Starter | 300 | 300 | 3,000 | 10 | | Scale | 1,000 | 1,000 | 15,000 | 10 | See the sending policy, anti-spam policy, acceptable use terms, and bounce/complaint handling pages before enabling outbound sending. ## 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 ``` Run this smoke only after DNS records are published and the selected mail provider reports receive and send readiness for the domain.