---
name: email-cli
description: Use this skill to operate the Mere Email CLI for workspace email setup, mailbox and thread workflows, outbound send, imports, exports, and authenticated automation.
---

# Email CLI

Use this skill for requests that touch the standalone Email app’s operator workflow.

## Scope

- CLI command surface in `email/cli/*`, especially `email/cli/mere-email.ts`, `email/cli/client.ts`, `email/cli/auth.ts`, and `email/cli/session.ts`.
- Local CLI auth/session flow (`auth`, saved session, and token mode).
- Internal API route usage under `email/src/routes/api/cli/v1` and `email/src/routes/api/internal/mere/workspaces/[workspaceId]`.
- Workspace lifecycle operations and mailbox/thread message operations requested by operators or automation.

## Base commands and environment

1. Set base URL:
   - `--base-url` flag or `MERE_EMAIL_BASE_URL`.
2. Resolve workspace:
   - `--workspace` flag or `MERE_EMAIL_WORKSPACE_ID`.
3. Prefer script-safe output with `--json` when integrating with other tasks.
4. Use `completion [bash|zsh|fish]` for shell setup.
5. Use `--yes --confirm <exact-id>` for non-interactive destructive flows.

## Immediate runbook

1. Build the CLI: `cd email && pnpm build:cli`.
2. Authenticate:
   - `./dist/run.js --base-url https://mere.email auth login`
   - `./dist/run.js auth whoami`
3. Validate workspace context for all non-auth commands.
4. Execute domain command:
   - mail read/send: `mailboxes`, `threads`, `attachments`, `send`.
   - lifecycle: `workspace`.
   - migrations/state ops: `export`, `import`, `inbound`.

## Reference documents

- [command-reference.md](references/command-reference.md): complete command syntax, flags, and handler mapping.
- [route-map.md](references/route-map.md): canonical internal route map and corresponding source files.

## Workflow patterns

### Operator auth

1. Run `auth login` and follow browser prompt.
2. The shared product auth contract uses `/api/cli/v1/auth/start`, `/authorize`, `/exchange`, `/refresh`, and `/logout`.
3. Re-run without `--workspace` if the requested workspace is unavailable.
4. Confirm context with `auth whoami`.
5. Local sessions keep refresh-token state and renew CLI access through `/refresh` automatically when needed.
6. Remove local auth state using `auth logout` when needed.

### Workspace operations

1. Ensure workspace id is set.
2. Run one action:
   - `workspace bootstrap`
   - `workspace provision` (required flags include slug/name/organization-id/callback-url/callback-bearer-token)
   - `workspace sync`
   - `workspace disconnect`
3. Review structured output before the next step.

### Mailbox/thread workflows

1. `mailboxes list` to inspect available mailboxes.
2. `threads search <query> [--limit N]` where `N` is 1..25.
3. `threads show <thread-id>` to inspect full thread state.
4. `threads read|star|archive <thread-id>` for thread actions.
5. `attachments list <thread-id>` to inspect stored files and `attachments download <attachment-id> --output FILE` to fetch bytes.

### Outbound + migration tasks

1. Send mail with `send`, requiring at least one `--to`.
2. Use `--cc` and `--bcc` only when needed.
3. Optionally scope by `--mailbox-id` and reply chains with `--reply-thread-id`.
4. Use `export` for backup/state capture.
5. Use `import --file` for load operations and `import status [--run-id]` for run tracking.
6. Use `inbound --file` to simulate ingress parsing for tests.

## Validation notes

- Non-auth commands require workspace context before request dispatch.
- `send` requires at least one `--to` value.
- `threads` actions require one thread id.
- `attachments download` requires an explicit `--output` path and token-auth workspace context.
- `import` validates payload shape and tenant id; workspace mismatch is a hard error.
- Auth uses the shared dedicated-token browser flow and local session cache:
  - session file path from `session.ts`: `~/.local/state/mere-email/session.json`.
  - `MERE_EMAIL_TOKEN` is accepted as automation override.

## Safe changes and edits

- For command behavior changes, edit:
  - `email/cli/mere-email.ts` (routing/validation/argument grammar).
  - `email/cli/client.ts` (HTTP targets/parsing).
- For auth/session behavior changes, edit:
  - `email/cli/auth.ts`, `email/cli/session.ts`.
- For runtime behavior changes, edit:
  - `email/src/routes/api/internal/mere/[...path]/+server.ts`, legacy `email/src/routes/api/internal/zerosmb/workspaces/[workspaceId]/*`, and CLI auth handlers in `email/src/routes/api/cli/v1/*`.
- Do not edit generated artifacts directly (`worker.js`).