Metadata-Version: 2.5
Name: nmail-cli
Version: 0.4.3
Summary: Nmail 对外 API 命令行客户端——为 agent/skill 设计（JSON envelope + exit code 契约 + 两阶段确认）
Author: Nmail
License: MIT
Requires-Python: >=3.11
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# nmail-cli

Nmail 对外 API 的命令行客户端（AGENT_SKILL_PLAN P2 / REDESIGN_PLAN §19）——为外部
agent 与 skill 设计：JSON envelope（stdout）、exit code 契约、发送类两阶段确认。

## 安装

```bash
uvx nmail-cli@latest --help     # 零安装（PyPI 发布后）
# 或
pipx install nmail-cli
```

发布随主仓发版流程进行（`nmail-cli` 为独立 PyPI 包名）。

## 快速上手

```bash
nmail-cli auth login                 # 本机 Nmail（127.0.0.1:8720）自动配对建 Key（默认 read scope）
nmail-cli auth login --scopes read,write,send   # 需要发送时显式扩权
nmail-cli +me                        # 账号列表与健康
nmail-cli emails list --limit 5
nmail-cli emails read 254 --save-attachments ./downloads
nmail-cli drafts reply --email-id 254 --body-file ./reply.md
nmail-cli drafts send 44             # 第一阶段：打印摘要，exit 8
nmail-cli drafts send 44 --confirmed # 第二阶段：用户许可后重放
nmail-cli watch                      # NDJSON 每行一封新邮件
```

远程（自建隧道）：`nmail-cli auth login --base-url https://nmail.example.com --key nmail_xxx`
（`/api/extkeys` 管理面仅本机可达，远程需从 Nmail 设置-API 复制 Key 粘贴）。

## 契约

- **stdout** 只输出 JSON envelope：成功 `{"ok":true,"data":…}`，失败
  `{"ok":false,"error":{"code","message",…}}`；人话日志走 stderr。
- **exit code**：`0` 成功 · `1` 上游 5xx 可重试×2 · `2` 参数不合规不重试 · `3` 认证失效/未启用
  走 `auth login` · `4` 连不上（检查 Nmail 是否运行/隧道） · `6` 业务永久拒绝不重试 ·
  `7` 限流按 `Retry-After` 等待 · `8` 需两阶段确认（停下等用户，不得同轮自确认）。
- 配置：`~/.config/nmail-cli/config.json`（0600）；环境变量 `NMAIL_BASE_URL` / `NMAIL_API_KEY`
  可覆盖（CI/一次性场景）。

服务端 API 与安全模型见 `docs/对外API使用指南.md`；面向 agent 的技能说明见 `skills/SKILL.md`（P3）。
