moemail/specs/2026-03-22-moemail-cli-design.md

MoeMail CLI — Agent-First Command Line Tool

Overview

A CLI tool that wraps MoeMail's existing OpenAPI, optimized for AI Agent workflows. Agents can create temporary emails, wait for incoming messages, read content, and manage mailboxes through simple shell commands.

Goal: Make MoeMail a first-class tool in any AI Agent's toolchain with minimal friction — one command per action, structured JSON output, minimal server-side changes.

Server-side changes: One small change required — the POST /api/emails/{id}/send endpoint currently uses session-only auth. It needs to be updated to also support API Key auth (switch from auth() to getUserId()) so the CLI send command works.

Architecture

Agent (Claude / GPT / Custom)
    ↓ shell call
moemail CLI (npm package, bun-built single JS file)
    ↓ HTTPS + X-API-Key header
MoeMail Server (existing Next.js API, one minor auth change for send endpoint)
    ↓
Cloudflare D1 / Email Workers

• Language: TypeScript
• Build: bun build ./src/index.ts --outdir ./dist --target=node
• Distribution: npm package, npm i -g moemail-cli
• Binary: package.json bin field points to dist/index.js
• Location: packages/cli/ in the monorepo
• Server changes: One change — update send endpoint to support API Key auth.

Configuration

Stored at ~/.moemail/config.json:

{
  "apiUrl": "https://moemail.app",
  "apiKey": "mk_xxxxxxxx"
}

Environment variable overrides (higher priority):

• MOEMAIL_API_URL
• MOEMAIL_API_KEY

Commands

All commands support --json for JSON output, --help for usage info, and moemail --version for version.

Field naming convention: CLI JSON output uses camelCase (messageId, receivedAt, fromAddress). The API uses snake_case (message_id, received_at, from_address). The CLI transforms all field names to camelCase, and converts epoch ms timestamps to ISO 8601 strings.

moemail config

# Interactive setup
moemail config

# Direct set
moemail config set api-url https://moemail.app
moemail config set api-key mk_xxxxxxxx

# View current config
moemail config list

moemail create

# Random prefix, 1h expiry (defaults)
moemail create

# With parameters
moemail create --name test --domain moemail.app --expiry 24h

--expiry options and API mapping:

CLI flag	API expiryTime (ms)
1h	3600000
24h	86400000
3d	259200000
permanent	0

Default output:

Created: test@moemail.app (expires in 24 hours)
ID: abc-123

JSON output (--json):

{"id": "abc-123", "address": "test@moemail.app", "expiresAt": "2026-03-23T12:00:00Z"}

Note: The API returns { id, email }. The CLI renames email → address for clarity, and computes expiresAt from the chosen expiry option.

moemail list

# List all mailboxes
moemail list

# List messages in a mailbox
moemail list --email-id xxx

# With pagination
moemail list --cursor xxx

JSON output — mailboxes (--json):

{"emails": [{"id": "abc-123", "address": "test@moemail.app", "expiresAt": "..."}], "nextCursor": "xxx", "total": 5}

JSON output — messages (--json --email-id xxx):

{"messages": [{"id": "msg-1", "from": "sender@example.com", "subject": "Hello", "receivedAt": "..."}], "nextCursor": null, "total": 2}

moemail wait

The core command for Agent workflows. Polls the API until a new message arrives or timeout.

# Wait for new message (default: 120s timeout, 5s interval)
moemail wait --email-id xxx

# Custom timeout and interval
moemail wait --email-id xxx --timeout 60 --interval 3

Parameters: --timeout and --interval are in seconds.

Behavior:

1. Fetch current message list, record all existing message IDs in a Set
2. Poll GET /api/emails/{id} every --interval seconds
3. Compare returned message IDs against the initial Set to detect new messages (ID-based, not count-based — safe against concurrent deletes)
4. On new message: output message summary and exit with code 0
5. On timeout: exit with code 1

Default output:

Polling... (15/120s)
New message from no-reply@github.com: "Verify your email"
Message ID: msg-456

JSON output (--json):

{"messageId": "msg-456", "from": "no-reply@github.com", "subject": "Verify your email", "receivedAt": "2026-03-22T12:05:00Z"}

moemail read

# Read message (default: plain text)
moemail read --email-id xxx --message-id yyy

# HTML format
moemail read --email-id xxx --message-id yyy --format html

--format options: text (default) | html

JSON output (--json):

{"id": "msg-456", "from": "no-reply@github.com", "to": "test@moemail.app", "subject": "Verify your email", "content": "Your code is 123456", "html": "<p>Your code is 123456</p>", "receivedAt": "2026-03-22T12:05:00Z", "type": "received"}

moemail send

moemail send --email-id xxx --to user@example.com --subject "Hello" --content "Body text"

JSON output (--json):

{"success": true, "remainingEmails": 4}

moemail delete

# Delete mailbox and all messages
moemail delete --email-id xxx

# Delete single message
moemail delete --email-id xxx --message-id yyy

JSON output (--json):

{"success": true}

Output Specification

Modes

Mode	Flag	Format	Use case
Text	(default)	Human-readable	Debugging, manual use
JSON	--json	Single-line JSON on stdout	Agent consumption

Exit Codes

Code	Meaning
0	Success
1	Operation failed (timeout, not found, bad params)
2	Auth failed (invalid/expired API Key)

Error Handling

• Errors write to stderr, never stdout
• In --json mode, stdout contains only valid JSON (or nothing on failure)
• Agent reads stdout for data, checks exit code for success/failure

$ moemail wait --email-id xxx --timeout 10 --json
# stderr: Polling... (3/10s)
# stderr: Timeout: no new messages received
# stdout: (empty)
# exit code: 1

Project Structure

packages/cli/
├── src/
│   ├── index.ts          # Entry point, command registration
│   ├── commands/
│   │   ├── config.ts     # config command
│   │   ├── create.ts     # create command
│   │   ├── list.ts       # list command
│   │   ├── wait.ts       # wait command (client-side polling)
│   │   ├── read.ts       # read command
│   │   ├── send.ts       # send command
│   │   └── delete.ts     # delete command
│   ├── api.ts            # HTTP client wrapping all API calls
│   ├── config.ts         # Read/write ~/.moemail/config.json
│   └── output.ts         # Output formatting (text / json)
├── package.json
├── tsconfig.json
└── README.md

Dependencies

• commander — CLI argument parsing and subcommand routing
• All other needs (HTTP, filesystem) use Node.js built-in APIs

Relationship to Main Project

• Lives in packages/cli/, published as a separate npm package
• No code shared with the main Next.js app
• Only coupling is the API contract (URLs, request/response shapes)
• Server-side: one change — send endpoint auth support for API Key

CI/CD Publishing

CLI 通过独立的 GitHub Actions workflow 发布到 npm，与主项目的 deploy workflow 分开。

Workflow: .github/workflows/publish-cli.yml

触发条件：

• Push tag 匹配 cli-v*（如 cli-v1.0.0），与主项目的 v* tag 区分

流程：

1. Checkout 代码
2. Setup pnpm + Node.js 20
3. Install dependencies（pnpm install --frozen-lockfile）
4. Build CLI（cd packages/cli && bun build ./src/index.ts --outdir ./dist --target=node）
5. Publish to npm（cd packages/cli && npm publish --access public）

所需 Secrets：

• NPM_TOKEN：npm publish token，在 GitHub repo Settings → Secrets 中配置

发布步骤

# 1. 更新 packages/cli/package.json 中的 version
# 2. Commit & push
# 3. 打 tag 并推送
git tag cli-v1.0.0
git push origin cli-v1.0.0

版本策略

CLI 独立版本号，不与主项目同步。遵循 semver：

• patch：bug fix
• minor：新增命令或 flag
• major：破坏性变更（命令重命名、输出格式变更）

Agent Discoverability

三层机制让 AI Agent 知道如何使用 CLI。

1. CLI 内置 Help

Commander 自动生成，Agent 调用一次即可获取完整用法：

$ moemail --help
Usage: moemail [options] [command]

MoeMail CLI — Agent-friendly temporary email tool

Options:
  -V, --version       output the version number
  --json              output as JSON
  -h, --help          display help for command

Commands:
  config              configure API endpoint and API Key
  create [options]    create a temporary email address
  list [options]      list mailboxes or messages
  wait [options]      wait for a new email to arrive
  read [options]      read an email message
  send [options]      send an email from a temporary address
  delete [options]    delete a mailbox or message

$ moemail create --help
Usage: moemail create [options]

Create a temporary email address

Options:
  --name <name>       email prefix (default: random)
  --domain <domain>   email domain
  --expiry <expiry>   1h | 24h | 3d | permanent (default: "1h")
  --json              output as JSON
  -h, --help          display help for command

2. README 文档

packages/cli/README.md 作为 npm 包首页展示，包含：

• 一句话介绍：Agent-first CLI for MoeMail temporary email service
• 安装命令
• 快速开始（3 步：config → create → wait）
• 完整命令参考表
• Agent workflow 示例
• JSON 输出格式说明

3. llms.txt

在 MoeMail 站点根目录提供 https://moemail.app/llms.txt，遵循 llms.txt 协议。Agent 访问网站时自动发现可用工具。

# MoeMail

> Temporary email service with CLI tool for AI Agents

MoeMail provides disposable email addresses. Install the CLI for programmatic access:

## CLI Tool

Install: npm i -g moemail-cli

Setup: moemail config set api-url https://moemail.app && moemail config set api-key YOUR_KEY

Commands:
- moemail create --domain <domain> --expiry <1h|24h|3d|permanent> --json
- moemail list --json
- moemail list --email-id <id> --json
- moemail wait --email-id <id> --timeout <seconds> --json
- moemail read --email-id <id> --message-id <id> --json
- moemail send --email-id <id> --to <addr> --subject <subj> --content <body> --json
- moemail delete --email-id <id> --json

Typical workflow: create email → use address for signup → wait for verification → read content → extract code → delete

All commands support --json for structured output. Exit code 0 = success, 1 = failure, 2 = auth error.

实现方式： 在 Next.js 的 public/ 目录下放置 llms.txt 静态文件，部署时自动可访问。

Typical Agent Workflow

# 1. Create a temporary mailbox
EMAIL=$(moemail create --domain moemail.app --expiry 1h --json)
EMAIL_ID=$(echo $EMAIL | jq -r '.id')
ADDRESS=$(echo $EMAIL | jq -r '.address')

# 2. Use the address to sign up for a service (agent does this elsewhere)

# 3. Wait for verification email
MSG=$(moemail wait --email-id $EMAIL_ID --timeout 120 --json)
MSG_ID=$(echo $MSG | jq -r '.messageId')

# 4. Read the email content
CONTENT=$(moemail read --email-id $EMAIL_ID --message-id $MSG_ID --json)

# 5. Agent extracts verification code from content (LLM does this)

# 6. Clean up
moemail delete --email-id $EMAIL_ID