跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

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 没有关联,也未获其认可。

这个页面有帮助吗?