Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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
  • 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.

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.

Was this page helpful?