CLI
@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. The package is @billionsend/cli on npm and its source is billionsend/billionsend-cli on GitHub.
Install
Needs Node 18 or newer. Run it without installing:
npx @billionsend/cli migrate --from resend
Or install it once:
npm install -g @billionsend/cli
billionsend --version
Commands
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
migrateis 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 planshows what would change and writes nothing. Before any write it checks your plan’s limits throughGET /usageand says what does not fit, for example “7 domains to create; the Free plan allows 3”. It also estimates the time.migrate applyapplies 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 statusshows what the last run created and what is left on the checklist. It needs no keys.migrate rollbackdeletes only what this tool created, never rows it only updated. It prints the list and asks first (--yesskips 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
401or403stops the run. The tool does not retry or work around it. - Rate limits are respected. On
429it waits forretry-after. On a server or network error it retries up to 5 times with growing pauses. - Opt-outs are kept.
unsubscribedand topic opt-outs are copied as they are, and nobody is re-subscribed. See 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:
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:
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.