# @flowmails/cli 中文文档

规范地址：https://npmcn.com/package/%40flowmails/cli/

版本：0\.1\.1
npm 元数据更新时间：2026-11-01T02:44:33.068Z
中文译文更新时间：2026-11-01T04:36:36.130Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flowmails/cli
原文对照：https://npmcn.com/package/%40flowmails/cli/?lang=original
项目主页：https://flowmails.net/docs/cli
源码仓库：https://github.com/wms-why/flowmails-cf

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：355 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2026-10-30T16:16:15.050Z
- 最新版本发布：2026-11-01T02:44:32.907Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

该流程邮件CLI -登录，测试，地址，观察，等待。建立在@flowmail /flowmail -sdk。

## 安装

```sh
npm install @flowmails/cli
```

也可以使用：`pnpm add @flowmails/cli`、`yarn add @flowmails/cli`、`bun add @flowmails/cli`

## README

# `@flowmails/cli` - - - `flowmails` 命令

flowmail CLI：围绕官方SDK的一个瘦的、可编写脚本的shell （[`@flowmails/flowmails-sdk`](https://npmcn.com/package/%40flowmails/sdk)）. 它存在，所以一个代理 人-可以检查连接，查看邮箱帐户 拥有、跟踪入站日志并等待消息 **没有 手动处理HTTP**.

它实现了AP-06 [`docs/agent-platform.md`](https://npmcn.com/package/docs/agent-platform.md) (§6.3,§10.4)。

* * *

## 安装

```bash
npm i -g @flowmails/cli
```

二进制文件叫做 `flowmails`：

```bash
flowmails --help
```

### 它需要的SDK

CLI是建立在 `@flowmails/flowmails-sdk` 和 **使它 外部** -发布的二进制文件在运行时导入SDK 而不是把它装在包里。因此，已公布的舱单 针一 **确切的** SDK版本，CLI需要：

|  |  |
| --- | --- |
| `@flowmails/cli` | `0.1.1` |
| `@flowmails/flowmails-sdk` | `0.2.1` (完全) |

`flowmails --version` 在标准输出和中打印CLI的版本 标准误差所需的SDK； `flowmails --help` 也说了。

别针是一种契约，而不是一种形式： `0.2.0` 是否打开了最新的SDK 公共登记处，它已经 **否 `fm.workerVersion()`** ——唯一的 代理可以询问“我的接收工作者是否足够新以填充我的事件。 日志吗?”一个固定在 `0.2.0` 我不能回答这个问题 user （audit p0 - 4,2026-10-31）。

**发布订单事项。** SDK必须达到npm **之前** CLI, 因为CLI的安装会提取清单名称的确切版本。 从repo根目录：

```bash
pnpm run publish:sdk   # @flowmails/flowmails-sdk 0.2.1
pnpm run publish:cli   # @flowmails/cli 0.1.1
```

要使用CLI本身，可以通过签出方式安装它：

```bash
# from the repo root
pnpm install
pnpm --filter @flowmails/cli build

# put `flowmails` on your PATH (a symlink into the checkout)
cd packages/cli && npm link
```

如果没有链接，直接从checkout中运行bundle：

```bash
node packages/cli/dist/cli.js --help
```

构建需要SDK的包，因为CLI是构建在它上面的：

```bash
pnpm --filter @flowmails/flowmails-sdk build   # builds packages/sdk/dist
pnpm --filter @flowmails/cli build             # bundles packages/cli/dist
```

两个 `build` 和 `typecheck` 在此包中先运行SDK构建， 所以 `pnpm --filter @flowmails/cli build` 它本身就足够了。

检查:

```bash
flowmails --help
```

## 人类只做一次入职

**命令行无法板载帐号，座席也不能。** 这些 按照设计，步骤仅在仪表板上显示：

-   创建flowmail帐户并登录；
-   连接Cloudflare帐户；
-   添加并验证一个域（DNS记录是你的）；
-   部署每个帐户的接收工作者；
-   生成API密钥本身。

每天做一次。 **[https://flowmails.net/dashboard/onboarding \*](https://flowmails.net/dashboard/onboarding*)\*，然后创建键at **[https://flowmails.net/dashboard/settings/api-keys \*](https://flowmails.net/dashboard/settings/api-keys*)\*并把它交给 CLI。之后，CLI所做的一切都是从命令开始的 Line -包括创建一个邮箱并等待第一封邮件。****

## `flowmails login` -存储凭证

> **设备流程尚未实现** (AP-07)。没有 要与之通信的设备端点 `flowmails login` 做 **不** 为您进行身份验证：它存储您粘贴的密钥。它是这么说的 运行的时间——CLI从来不会在没有登录的时候假装已经登录。

```bash
flowmails login                      # prompts for the key (input is not echoed)
flowmails login --key fm_…           # non-interactive
cat key.txt | flowmails login        # non-interactive, from stdin
```

该密钥通过形状进行验证，并以mode存储在配置文件中 `0600`. **没有任何命令打印原始密钥** -输出显示短 前缀(`fm_012…`)，仅此而已。

### 凭证类型

| 前缀 | 它是什么？ |
| --- | --- |
| `fm_…` | SDK密钥。一个租户，绑定一个域发送。 |
| `agc_…` | 代理凭证。同一个租户加上一个范围列表。 |

两者都被 `flowmails login`.

## `flowmails test` -连接检查

这是安装说明告诉您要运行的第一件事 “到第一个代理行动的时间”指标中的第一个信号。它是 安静（标准输出上一行，标准输出上的步骤）和果断（标准输出上的步骤） 退出代码意味着什么)。

```bash
flowmails test
# flowmails test: OK — credential fm_012…, domain yourapp.com, API alive (no message sent), domain can send
```

它检查四件事：

1.  **身份验证** -该证书被平台接受。
2.  **域** -该帐户拥有哪个域，以及该帐户拥有哪个域 钥匙是绑定的。(平台不会将绑定暴露给 范围凭证- `GET /api/v1/me` SDK密钥的表面是什么 对于几个域，CLI会说“未知”而不是猜测。)
3.  **API活性** -发送源 _答案_ 对于这个证书。 **没有邮件发送。**
4.  **发送能力** -边界域是否可以 发送。平台将其报告在代理的域投影上 （`canSend` + `sendingState`)等等 `GET /api/v1/me`.

### 步骤3是活体检查，而不是发送

探针读取不存在的消息id的状态，因此a `404` 是证明API可达的答案。这是 **所有** 它证明了。用于将其称为“发送可达性”并打印的命令 `flowmails test: OK` 对于发送失败的域 **100％** 的 Time—新用户运行的第一个命令（audit）为false positive P0-2, 2026-10-31)。

所以索赔现在是索赔：支票上写着 **“API活着”**, 这个 _能力_ 从平台读取。

### 判决结果

| 判决 | 退出 | 意义 |
| --- | --- | --- |
| `OK` | `0` | 通过认证，API是活的， **束缚域可以发送**. |
| `UNVERIFIED` | `0` | 通过身份验证后，API是活动的，但平台不报告域是否可以发送（旧的后端）。这是 **不** 通过验证 `flowmails test --send-to <addr>`. |
| `FAILED` | `1` | 有些东西坏了：凭证被拒绝，平台无法访问，或者 **绑定域无法发送**． 消息命名域。 |

无法发送的域 **从来没有** 打印 `flowmails test: OK`.

```bash
flowmails test
# ✓ auth ok (fm_012…)
# ✓ domains: mysoul.fun
# ✓ bound domain: mysoul.fun
# ✓ API alive (no message sent)
# ✓ domain mysoul.fun cannot send (not_onboarded)
# ✗ mysoul.fun cannot send (sending state: not_onboarded)
# flowmails test: FAILED — fm_012…, mysoul.fun cannot send (sending state: not_onboarded)
# $? = 1
```

(前五行是进展轨迹 **stderr**;这个 `FAILED` 行是总结，也对stderr。与 `--json` 摘要 是标准输出上的一个JSON对象。)

### 发送真实信息是可选择的

默认情况下不发送任何内容。真正的信息只有在你请求的时候才会发送 一:

```bash
flowmails test --send-to someone@example.com
```

`--from <local@domain>` 时，将覆盖发件人地址 拥有多个域名。平台记录为失败的发送 （`status: "failed"`，审计p -1)也没有通过检查，与 平台给出的理由。

### 机器可读的输出

```bash
flowmails test --json
# {"ok":true,"verdict":"ok","credential":"fm_012…","domains":[…],"boundDomain":"yourapp.com",
#  "api":{"alive":true},"send":{"canSend":true,"state":"ready","verifiedBy":"capability","sent":null}}
```

`verdict` 是 `ok`， `unverified` 或者 `failed`； `send.canSend` 是 `null` 当平台没有报告时。

## `flowmails addresses` ——你自己的邮箱

```bash
flowmails addresses
# yourapp.com (catchall, ready)
#   billing@yourapp.com

flowmails addresses --json
# {"domains":[{"id":"dom_1","name":"yourapp.com","routingMode":"catchall","ready":true,…}]}
```

在一个 `catchall` 域各局部交付；在一个 `rules` 域 只有列出的那些才有——清单会告诉你是哪些。

## `flowmails watch <addr>` -跟踪入站日志

```bash
flowmails watch billing@yourapp.com
{"id":"evt_…","messageId":"<…>","event":"inbound.received","recipient":"billing@yourapp.com","sender":"stripe@example.com","subject":"Your invoice","createdAt":"…"}
```

每行一个JSON对象，换行分隔，因此它直接管道到 `jq` 或者行阅读器。事件携带路由事实和主题 - - - - - - **从来没有尸体**;用SDK获取主体 `messages.get()`.

## `flowmails wait <addr>` -等待消息

```bash
flowmails wait billing@yourapp.com
# <3f8a…@stripe.example>          # the resolved SMTP Message-ID

flowmails wait billing@yourapp.com --subject invoice --sender stripe@example.com --timeout 5m
```

平台上的等待是持久的：它立即回答 解析匹配的消息何时登陆，并在CLI运行时存活 死亡。标准输出只携带一样东西——已解决的 消息id -这样命令可以在替换中使用：

```bash
id=$(flowmails wait billing@yourapp.com)
```

等待时观察到的事件是JSON行 **stderr**.

**过期不是失败。** 等待到了最后期限，没有 匹配的消息退出 `3` (过期);一个无法完成它的等待 出口工作 `1` (失败)。它们以前是相同的代码，剩下一个 脚本无法区分“超时”和“损坏”（审计P1-6） 2026-10-31)。

## 断开连接后继续

`watch` 和 `wait` 持久化它们的游标——最后一个事件的id 它们将-打印到状态文件，并在下次运行时从它恢复：

-   游标是 **标识符**，一个时间戳（两个事件）永远不能 在同一毫秒内着陆，可以跳过一行的游标就会丢失 邮件);
-   是这样写的 **后** 每个事件都被打印出来，这样之间就会崩溃 两个事件重播 **最多是最后一个**.

这是 **至少一次交付**这是一门正确的行业 另一种选择是无声地丢失邮件。如果你的消费者需要 正好一次，重复一次 `messageId`.

失败的页面（丢失的套接字，502）不会结束命令 在stderr上报告错误，并从游标恢复下一个轮询 它已经在磁盘上了。平台不知道的游标是A 不同的失败——平台回答 `400`，而不是空白页，所以 `watch` 停止并表示要删除状态文件，而不是旋转或 默默地重播整个日志。 `wait` 此外，还坚持 **等待id**，因此重新连接将恢复 _相同_ 等一等，不要再打开了 一个。

## 文件

| 路径 | 模式 | 它包含什么 |
| --- | --- | --- |
| `~/.config/flowmails/config.json` | `0600` | 凭据，可选 `baseURL` / `platformURL` 覆盖。 |
| `~/.config/flowmails/state.json` | `0600` | 每个命令和邮箱的游标（和等待id）。 |

使用mode创建目录 `0700`． 两条路径都是 重写:

```bash
flowmails --config /path/to/config.json test
FLOWMAILS_CONFIG=/path/to/config.json flowmails test
FLOWMAILS_STATE=/path/to/state.json flowmails watch billing@yourapp.com
```

`$XDG_CONFIG_HOME` 的默认位置。

## 命令表面

```
flowmails login [--key <key>]              Store a credential (paste-key fallback)
flowmails test [--send-to <addr>]          Connection check: auth, domain, API liveness, send capability
flowmails addresses [--json]               List the account's domains and mailboxes
flowmails watch <addr>                     Tail inbound events as JSON lines
flowmails wait <addr> [--subject <s>] [--sender <s>] [--timeout <ms>]
                                            Wait for a message and print its id
```

全局选项: `--config <path>`， `--state <path>`， `--json`， `-h/--help`， `-v/--version`.

`flowmails <command> --help` 打印该命令自己的帮助- its 选项和退出代码表。

`--timeout` 接受毫秒数(`60000`)或持续时间(`30s`， `5m`， `1h`）。

## 退出代码

出口密码是a **合同**：一个脚本分支在它们上面，所以a 有两种含义的代码是bug。

| 代码 | 意义 |
| --- | --- |
| `0` | 成功-命令完成了它被要求做的事情。 |
| `1` | 失败-凭证被拒绝，平台不可达，绑定域无法发送，或命令遇到错误。 |
| `2` | 使用错误-未解析参数。 |
| `3` | 过期, `flowmails wait` 到了最后期限，却没有收到匹配的信息。 |

`3` 是分开的 `1` 故意的：“timed out”和“broken”是 不同的答案，脚本无法区分它们 设置永远损坏，并放弃一个健康的邮箱，只是 没有邮件（审计P1-6, 2026-10-31）。

`flowmails test` 出口 `0` 对于 `OK` 和 `UNVERIFIED` -什么都不是 已知在第二种情况下是坏的-所以阅读 **判决** 在 总结(`OK` / `UNVERIFIED` / `FAILED`)，而不仅仅是退出密码。

## 这个包裹不是什么

-   它是 **不** 一个入职工具。请看上面的边界。
-   它是 **不** MCP服务器（即AP-09），它不公开 十个代理工具-它是一个命令行表面相同 SDK。
-   它 **不** 实现设备流程（AP-07）。
-   它 **不** 暴露每个工具的作用域(AP-03) - SDK密钥是 租户范围的读取加上域绑定的发送。

## 开发

```bash
pnpm --filter @flowmails/cli typecheck
pnpm --filter @flowmails/cli build
node --test ./test/cli-*.test.mjs   # from the repo root
```

命令逻辑驻留在下面的小模块中 `src/commands/`, SDK客户端是通过运行时注入的——所以测试驱动 命令不需要网络，不需要进程，也不需要 SDK的包。

## 常见问题

### @flowmails/cli 是什么？

该流程邮件CLI -登录，测试，地址，观察，等待。建立在@flowmail /flowmail -sdk。

### 如何安装 @flowmails/cli？

在项目目录运行 npm install @flowmails/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 flowmails，可以用 npx flowmails 直接运行。

### @flowmails/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flowmails\_\_cli 是否存在。

### @flowmails/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @flowmails/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flowmails/cli 可以商用吗？

@flowmails/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flowmails/cli 还在维护吗？

最新版本 0\.1\.1 发布于 2026/11/01（2 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。