mirror of
https://github.com/beilunyang/moemail.git
synced 2026-06-25 09:24:35 +08:00
b99b872791
Extract the HTTP client and config into a new @moemail/core package shared by the CLI and a new @moemail/mcp server, so both frontends talk to the same MoeMail API through one code path. - core: api client (now throws typed ConfigError/AuthError/PermissionError/ QuotaError instead of process.exit), config, msToIso, and a transport- agnostic pollForNewMessage helper. - cli: consume @moemail/core; route command errors through a shared fail() that preserves exit codes (config/auth = 2, else = 1). Bump to 1.0.0. - mcp: new stdio MCP server exposing 8 tools (create/list/read/wait/send/ delete); wait_for_email is bounded and returns a timeout status to retry. Configured via MOEMAIL_API_KEY / MOEMAIL_API_URL env. Release 1.0.0. Docs: - Fix packages/cli/README.md (config set, send --content not --body, full flag table). - Add MCP section to both root READMEs; complete the CLI command list (send, list, message-level delete). - SKILL.md: --json works before or after the subcommand. - Ignore bun.lock in package gitignores. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
108 lines
3.4 KiB
Markdown
108 lines
3.4 KiB
Markdown
# MoeMail CLI
|
|
|
|
Agent-first CLI for MoeMail temporary email service
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm i -g @moemail/cli
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### 1. Configure endpoint and API key
|
|
```bash
|
|
moemail config set api-url https://moemail.app
|
|
moemail config set api-key YOUR_API_KEY
|
|
```
|
|
|
|
> Config is read from `~/.moemail/config.json`, or overridden by the
|
|
> `MOEMAIL_API_URL` / `MOEMAIL_API_KEY` environment variables.
|
|
|
|
### 2. Create a temporary email
|
|
```bash
|
|
moemail create --expiry 1h
|
|
```
|
|
|
|
### 3. Wait for messages
|
|
```bash
|
|
moemail wait --email-id <email_id> --timeout 120
|
|
```
|
|
|
|
## Command Reference
|
|
|
|
| Command | Description | Key Flags |
|
|
|---------|-------------|-----------|
|
|
| `config set` | Set `api-url` or `api-key` | `config set <api-url\|api-key> <value>` |
|
|
| `config list` | Show current configuration | — |
|
|
| `create` | Create a temporary email address | `--name <prefix>`, `--domain <domain>`, `--expiry <1h\|24h\|3d\|permanent>`, `--json` |
|
|
| `list` | List mailboxes, or messages in a mailbox | `--email-id <id>`, `--cursor <cursor>`, `--json` |
|
|
| `wait` | Wait for incoming messages | `--email-id <id>`, `--timeout <seconds>`, `--interval <seconds>`, `--json` |
|
|
| `read` | Read email message content | `--email-id <id>`, `--message-id <id>`, `--format <text\|html>`, `--json` |
|
|
| `send` | Send email from temporary address | `--email-id <id>`, `--to <address>`, `--subject <text>`, `--content <text>`, `--json` |
|
|
| `delete` | Delete a mailbox, or a single message | `--email-id <id>`, `--message-id <id>` |
|
|
| `skill install` | Install AI agent skill | `--platform <claude\|codex\|all>` |
|
|
|
|
## Agent Workflow Example
|
|
|
|
The CLI is designed to support agent-first automation. Here's a typical workflow:
|
|
|
|
```bash
|
|
# Create temporary email and extract details
|
|
EMAIL=$(moemail create --domain moemail.app --expiry 1h --json)
|
|
EMAIL_ID=$(echo $EMAIL | jq -r '.id')
|
|
ADDRESS=$(echo $EMAIL | jq -r '.address')
|
|
|
|
# Use ADDRESS for signup or service registration...
|
|
|
|
# Wait for verification email
|
|
MSG=$(moemail wait --email-id $EMAIL_ID --timeout 120 --json)
|
|
MSG_ID=$(echo $MSG | jq -r '.messageId')
|
|
|
|
# Read message content
|
|
CONTENT=$(moemail read --email-id $EMAIL_ID --message-id $MSG_ID --json)
|
|
|
|
# Extract verification code from CONTENT...
|
|
|
|
# Cleanup
|
|
moemail delete --email-id $EMAIL_ID
|
|
```
|
|
|
|
## AI Agent Skill
|
|
|
|
The CLI ships with a built-in skill file that teaches AI agents how to use MoeMail. Install it to your agent platform:
|
|
|
|
```bash
|
|
# Auto-detect installed platforms (Claude Code, Codex)
|
|
moemail skill install
|
|
|
|
# Install to a specific platform
|
|
moemail skill install --platform claude
|
|
moemail skill install --platform codex
|
|
|
|
# Install to all supported platforms (skip detection)
|
|
moemail skill install --platform all
|
|
```
|
|
|
|
After installation, AI agents will automatically know how to create temporary emails, wait for messages, and read content using the MoeMail CLI.
|
|
|
|
## JSON Output
|
|
|
|
All commands support `--json` flag for structured output, making them ideal for agent automation:
|
|
|
|
- **Success**: Command output in JSON format to stdout
|
|
- **Errors**: Error messages written to stderr
|
|
- **Exit Codes**:
|
|
- `0`: Command succeeded
|
|
- `1`: Runtime error (invalid input, service error)
|
|
- `2`: Configuration or authentication error (missing `api-url`/`api-key`, invalid credentials)
|
|
|
|
## Project Links
|
|
|
|
- **Main Project**: https://github.com/beilunyang/moemail
|
|
- **Issues & Feedback**: https://github.com/beilunyang/moemail/issues
|
|
|
|
## License
|
|
|
|
MIT
|