---
title: CLI
description: "@billionsend/cli 让你在终端里把邮件服务账号迁移到 BillionSend。"
seo:
  title: 邮件 CLI：迁移你的账号
ai:
  exclude: true
---

`@billionsend/cli` 用来把邮件服务账号迁移到 BillionSend。它读取源账号，与你的账号比较，应用差异并写出报告。目前唯一支持的源是 Resend。分步指南见[从 Resend 迁移](/docs/zh-hans/migrate-from-resend)。软件包是 npm 上的 [`@billionsend/cli`](https://www.npmjs.com/package/@billionsend/cli)，源码在 GitHub 的 [billionsend/billionsend-cli](https://github.com/billionsend/billionsend-cli)。

## 安装

需要 Node 18 或更高版本。无需安装，直接运行：

```sh
npx @billionsend/cli migrate --from resend
```

也可以一次性安装：

```sh
npm install -g @billionsend/cli
billionsend --version
```

## 命令

```sh
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` 和订阅主题的退订原样复制，不会让任何人重新订阅。见[退订](/docs/zh-hans/concepts/unsubscribes)。

## 退出码

| 退出码 | 含义 |
| --- | --- |
| `0` | 成功；对 `migrate plan` 来说，表示无需操作。 |
| `1` | 错误：参数有误、缺少输入、密钥被拒绝。 |
| `2` | 仅 `migrate plan`：计划里有变更。 |
| `3` | 部分完成：有些项目失败。见报告。 |

## 脚本与 CI

stdin 不是终端，或者使用了 `--non-interactive` 或 `--json` 时，工具从不提问。缺少输入时以 1 退出，并指出需要设置的变量或参数。请通过环境变量或 stdin 传入密钥，不要作为参数传入：

```sh
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` 输出报告），可以直接接入管道：

```sh
billionsend migrate plan --from resend --json | jq '.counts'
```

---

Resend 是 Plus Five Five, Inc. 的注册商标。BillionSend 与 Resend 没有关联，也未获其认可。
