CLI
@billionsend/cli 让你在终端里把邮件服务账号迁移到 BillionSend。
@billionsend/cli 用来把邮件服务账号迁移到 BillionSend。它读取源账号,与你的账号比较,应用差异并写出报告。目前唯一支持的源是 Resend。分步指南见从 Resend 迁移。软件包是 npm 上的 @billionsend/cli,源码在 GitHub 的 billionsend/billionsend-cli。
安装
需要 Node 18 或更高版本。无需安装,直接运行:
npx @billionsend/cli migrate --from resend
也可以一次性安装:
npm install -g @billionsend/cli
billionsend --version
命令
billionsend migrate --from resend # 连接、选择资源、生成计划、确认、应用
billionsend migrate plan --from resend [--out plan.json] # 只读:退出码 0 表示无需操作,2 表示有变更,1 表示出错
billionsend migrate apply [plan.json] [--yes] # 应用已保存的计划,或一次性生成并应用
billionsend migrate status # 上一次运行创建了什么,还剩什么
billionsend migrate rollback [--yes] # 只删除这个工具创建的内容
migrate是交互式路径。它会询问缺少的内容(密钥),让你选择资源,显示计划,请你确认,然后应用并打印汇总。migrate plan显示将会发生的变更,不写入任何内容。在任何写入之前,它会通过GET /usage检查你套餐的限额,并说明哪些放不下,例如「7 domains to create; the Free plan allows 3」。它还会估算所需时间。migrate apply应用已保存的计划,或一次完成生成与应用。联系人按邮箱地址匹配。其他一切按名称、键、端点或别名匹配,不同就更新,相同就保持不动。migrate status显示上一次运行创建了什么,以及检查清单上还剩什么。它不需要密钥。migrate rollback只删除这个工具创建的内容,绝不碰只是被它更新过的行。它会先打印清单并询问(--yes跳过询问)。
参数
| 参数 | 含义 |
|---|---|
--from <provider> |
源服务商。目前只有 resend。 |
--from-key-stdin |
从 stdin 读取源 API 密钥(第一行)。 |
--from-key <key> |
以参数形式传入源 API 密钥。进程列表里能看到,所以建议用环境变量。 |
--to-url <url> |
BillionSend API 地址。默认 https://api.billionsend.com。 |
--to-key-stdin |
从 stdin 读取 BillionSend API 密钥(两个 stdin 参数都设置时为第二行)。 |
--to-key <key> |
以参数形式传入 BillionSend API 密钥。同样需要注意上面的问题。 |
--rps <n> |
对源服务的每秒请求数。默认 8,最大 100。Resend 的限额是 10,并与你的生产发送共用。只有在 Resend 提高了你的限额之后,才可以超过 10。 |
--only <a,b> |
只迁移这些资源。 |
--skip <a,b> |
跳过这些资源。 |
--on-conflict <mode> |
对已存在的联系人:upsert(默认)、skip 或 error。 |
--include-sent |
把已发送的群发作为草稿导入。默认跳过。 |
--fresh-webhook-secrets |
创建新的 Webhook 签名密钥,而不是复制旧的。只在报告里显示一次。 |
--fresh |
忘掉续传进度,重新读取全部内容。之前运行创建的内容会保留,所以 rollback 仍然可用。 |
--out <file> |
migrate plan:把计划写成 JSON。 |
--report <file> |
同时把 Markdown 报告写到这个路径。 |
-y、--yes |
跳过确认。 |
--non-interactive |
从不提问。缺少输入时以 1 退出。stdin 不是终端时,以及使用 --json 时会自动启用。 |
--json |
stdout 输出 JSON,进度输出到 stderr。 |
-v、--verbose |
记录每一次请求。 |
--color <mode>、--no-color |
auto(默认)、always 或 never。 |
-h、--help / -V、--version |
帮助和版本。 |
--only 和 --skip 可用的资源,按应用顺序依次为:domains、properties、topics、segments、contacts、enrichment、broadcasts、templates、webhooks、suppressions、api-keys。enrichment 是第二遍,用来读取每个联系人的订阅主题和属性。
环境变量
| 变量 | 含义 |
|---|---|
RESEND_API_KEY |
源 API 密钥,完全访问。 |
BILLIONSEND_API_KEY |
你的 BillionSend API 密钥,完全访问。 |
BILLIONSEND_BASE_URL |
BillionSend API 地址,与 --to-url 相同。 |
NO_COLOR |
关闭颜色。 |
FORCE_COLOR |
即使经过管道也输出颜色。 |
每个密钥按这个顺序查找:环境变量、-stdin 参数、命令行参数,最后在终端里弹出隐藏输入的提示。
文件
工具会把这些文件写在你运行它的位置旁边,只有你自己可读,其中从不包含密钥:
| 文件 | 内容 |
|---|---|
.billionsend/migrate-state.json |
工具创建了什么、停在了哪里,这样中断的运行可以继续。 |
.billionsend/migrate-report.json |
上一次运行的报告,数据格式。 |
.billionsend/migrate-report.md |
同一份报告的 Markdown 版:数量、检查清单、每个域名的 DNS 记录、id 对照表(源端的订阅主题和分群 id 对应到 BillionSend 的 id)以及手动事项。 |
当前目录里有 .gitignore 时,.billionsend/ 会被加进去。
安全
- 只读取 Resend。 对 Resend 的每个请求都是
GET。写入只发往你的 BillionSend API。 - 密钥只留在内存里,并且会从每一行日志里隐去。没有遥测,也不检查更新。
- 遇到
401或403就停止。 工具不会重试,也不会绕过。 - 遵守速率限制。 遇到
429时会等待retry-after。遇到服务器或网络错误时,会以逐渐加长的间隔最多重试 5 次。 - 保留退订状态。
unsubscribed和订阅主题的退订原样复制,不会让任何人重新订阅。见退订。
退出码
| 退出码 | 含义 |
|---|---|
0 |
成功;对 migrate plan 来说,表示无需操作。 |
1 |
错误:参数有误、缺少输入、密钥被拒绝。 |
2 |
仅 migrate plan:计划里有变更。 |
3 |
部分完成:有些项目失败。见报告。 |
脚本与 CI
stdin 不是终端,或者使用了 --non-interactive 或 --json 时,工具从不提问。缺少输入时以 1 退出,并指出需要设置的变量或参数。请通过环境变量或 stdin 传入密钥,不要作为参数传入:
export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...
billionsend migrate plan --from resend --out plan.json
# 退出码 2 表示有内容需要应用
billionsend migrate apply plan.json --yes
使用 --json 时,stdout 只输出 JSON(migrate plan 输出计划,migrate apply 输出报告),可以直接接入管道:
billionsend migrate plan --from resend --json | jq '.counts'
Resend 是 Plus Five Five, Inc. 的注册商标。BillionSend 与 Resend 没有关联,也未获其认可。