---
title: CLI
description: "@billionsend/cli moves an email account to BillionSend from your terminal."
---

`@billionsend/cli` moves an email account to BillionSend. It reads the source account, compares it with yours, applies the difference and writes a report. Resend is the only source today. The step-by-step guide is [Migrate from Resend](/docs/migrate-from-resend). The package is [`@billionsend/cli` on npm](https://www.npmjs.com/package/@billionsend/cli) and its source is [billionsend/billionsend-cli](https://github.com/billionsend/billionsend-cli) on GitHub.

## Install

Needs Node 18 or newer. Run it without installing:

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

Or install it once:

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

## Commands

```sh
billionsend migrate --from resend                          # connect, choose resources, plan, confirm, apply
billionsend migrate plan --from resend [--out plan.json]   # read-only: exit 0 nothing to do, 2 changes, 1 error
billionsend migrate apply [plan.json] [--yes]              # apply a saved plan, or plan and apply at once
billionsend migrate status                                 # what the last run created and what is left
billionsend migrate rollback [--yes]                       # delete only what this tool created
```

- **`migrate`** is the interactive path. It asks for what is missing (keys), lets you pick resources, shows the plan, asks to confirm, applies it and prints a summary.
- **`migrate plan`** shows what would change and writes nothing. Before any write it checks your plan's limits through `GET /usage` and says what does not fit, for example "7 domains to create; the Free plan allows 3". It also estimates the time.
- **`migrate apply`** applies a saved plan, or plans and applies in one go. Contacts are matched by email. Everything else is matched by name, key, endpoint or alias, then updated when different and left alone when the same.
- **`migrate status`** shows what the last run created and what is left on the checklist. It needs no keys.
- **`migrate rollback`** deletes only what this tool created, never rows it only updated. It prints the list and asks first (`--yes` skips the question).

## Flags

| Flag | Meaning |
| --- | --- |
| `--from <provider>` | Source provider. Only `resend`. |
| `--from-key-stdin` | Read the source API key from stdin (first line). |
| `--from-key <key>` | Source API key as an argument. Visible in process lists, so prefer the environment variable. |
| `--to-url <url>` | BillionSend API URL. Default `https://api.billionsend.com`. |
| `--to-key-stdin` | Read the BillionSend API key from stdin (second line when both stdin flags are set). |
| `--to-key <key>` | BillionSend API key as an argument. Same caveat. |
| `--rps <n>` | Requests per second against the source. Default 8, up to 100. Resend's limit is 10 and shared with your production sending. Go above 10 only after Resend raised your limit. |
| `--only <a,b>` | Move only these resources. |
| `--skip <a,b>` | Skip these resources. |
| `--on-conflict <mode>` | For contacts that already exist: `upsert` (default), `skip` or `error`. |
| `--include-sent` | Import sent broadcasts as drafts. Skipped by default. |
| `--fresh-webhook-secrets` | Create new webhook signing secrets instead of copying the old ones. Shown once, in the report. |
| `--fresh` | Forget resume progress and read everything again. What earlier runs created is kept, so `rollback` still works. |
| `--out <file>` | `migrate plan`: write the plan as JSON. |
| `--report <file>` | Also write the Markdown report to this path. |
| `-y`, `--yes` | Skip confirmations. |
| `--non-interactive` | Never ask questions. A missing input exits with 1. Automatic when stdin is not a terminal, and with `--json`. |
| `--json` | JSON on stdout, progress on stderr. |
| `-v`, `--verbose` | Log every request. |
| `--color <mode>`, `--no-color` | `auto` (default), `always` or `never`. |
| `-h`, `--help` / `-V`, `--version` | Help and version. |

Resources for `--only` and `--skip`, in the order they are applied: `domains`, `properties`, `topics`, `segments`, `contacts`, `enrichment`, `broadcasts`, `templates`, `webhooks`, `suppressions`, `api-keys`. `enrichment` is the second pass that reads each contact's topic subscriptions and properties.

## Environment variables

| Variable | Meaning |
| --- | --- |
| `RESEND_API_KEY` | Source API key, full access. |
| `BILLIONSEND_API_KEY` | Your BillionSend API key, full access. |
| `BILLIONSEND_BASE_URL` | BillionSend API URL, same as `--to-url`. |
| `NO_COLOR` | Turn colors off. |
| `FORCE_COLOR` | Colors even when piped. |

Each key is looked up in this order: environment variable, `-stdin` flag, argument flag, then, in a terminal, a hidden prompt.

## Files

The tool writes these next to where you run it, readable only by you and never containing a key:

| File | Contents |
| --- | --- |
| `.billionsend/migrate-state.json` | What the tool created and where it stopped, so an interrupted run resumes. |
| `.billionsend/migrate-report.json` | The last run's report as data. |
| `.billionsend/migrate-report.md` | The same report as Markdown: counts, checklist, DNS records per domain, an id map (source topic and segment ids to BillionSend ids) and manual items. |

`.billionsend/` is added to `.gitignore` when there is one in the current directory.

## Safety

- **Resend is only read.** Every request to Resend is a `GET`. Writes go to your BillionSend API only.
- **Keys stay in memory** and are hidden from every log line. There is no telemetry and no update check.
- **A `401` or `403` stops the run.** The tool does not retry or work around it.
- **Rate limits are respected.** On `429` it waits for `retry-after`. On a server or network error it retries up to 5 times with growing pauses.
- **Opt-outs are kept.** `unsubscribed` and topic opt-outs are copied as they are, and nobody is re-subscribed. See [Unsubscribes](/docs/concepts/unsubscribes).

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success, or for `migrate plan`, nothing to do. |
| `1` | Error: bad arguments, missing input, rejected key. |
| `2` | `migrate plan` only: the plan has changes. |
| `3` | Partial: some items failed. See the report. |

## Scripts and CI

When stdin is not a terminal, or with `--non-interactive` or `--json`, the tool never asks questions. A missing input exits with 1 and names the variable or flag to set. Pass keys by environment variable or stdin, never as arguments:

```sh
export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...

billionsend migrate plan --from resend --out plan.json
# exit 2 means there is something to apply
billionsend migrate apply plan.json --yes
```

With `--json`, stdout carries only JSON (the plan for `migrate plan`, the report for `migrate apply`) so you can pipe it:

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

---

Resend is a registered trademark of Plus Five Five, Inc. BillionSend is not affiliated with or endorsed by Resend.
