---
title: CLI
description: "@billionsend/cli 讓你在終端機裡把電子郵件服務帳號遷移到 BillionSend。"
seo:
  title: Email CLI：遷移你的帳號
ai:
  exclude: true
---

`@billionsend/cli` 用來把電子郵件服務帳號遷移到 BillionSend。它讀取來源帳號，與你的帳號比對，套用差異並寫出報告。目前唯一支援的來源是 Resend。逐步指南見[從 Resend 遷移](/docs/zh-hant/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-hant/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 無關聯，也未獲其背書。
