CLI
@billionsend/cli move uma conta de e-mail para o BillionSend pelo seu terminal.
@billionsend/cli move uma conta de e-mail para o BillionSend. Ele lê a conta de origem, compara com a sua, aplica a diferença e escreve um relatório. O Resend é a única origem hoje. O passo a passo está em Migrar do Resend. O pacote é @billionsend/cli no npm e o código-fonte está em billionsend/billionsend-cli no GitHub.
Instalar
Precisa do Node 18 ou mais novo. Rode sem instalar:
npx @billionsend/cli migrate --from resend
Ou instale uma vez:
npm install -g @billionsend/cli
billionsend --version
Comandos
billionsend migrate --from resend # conectar, escolher recursos, planejar, confirmar, aplicar
billionsend migrate plan --from resend [--out plan.json] # só leitura: saída 0 nada a fazer, 2 mudanças, 1 erro
billionsend migrate apply [plan.json] [--yes] # aplicar um plano salvo, ou planejar e aplicar de uma vez
billionsend migrate status # o que a última execução criou e o que falta
billionsend migrate rollback [--yes] # apagar só o que esta ferramenta criou
migrateé o caminho interativo. Pede o que falta (chaves), deixa você escolher os recursos, mostra o plano, pede confirmação, aplica e imprime um resumo.migrate planmostra o que mudaria e não escreve nada. Antes de qualquer escrita, ele confere os limites do seu plano porGET /usagee diz o que não cabe, por exemplo “7 domains to create; the Free plan allows 3”. Também estima o tempo.migrate applyaplica um plano salvo, ou planeja e aplica de uma vez. Os contatos são casados pelo e-mail. O resto é casado por nome, chave, endpoint ou alias, e então atualizado quando diferente e deixado como está quando igual.migrate statusmostra o que a última execução criou e o que resta na lista de tarefas. Não precisa de chaves.migrate rollbackapaga só o que esta ferramenta criou, nunca linhas que ela apenas atualizou. Ele imprime a lista e pergunta antes (--yespula a pergunta).
Flags
| Flag | Significado |
|---|---|
--from <provider> |
Provedor de origem. Só resend. |
--from-key-stdin |
Lê a chave de API de origem do stdin (primeira linha). |
--from-key <key> |
Chave de API de origem como argumento. Fica visível na lista de processos, então prefira a variável de ambiente. |
--to-url <url> |
URL da API do BillionSend. Padrão https://api.billionsend.com. |
--to-key-stdin |
Lê a chave de API do BillionSend do stdin (segunda linha quando as duas flags de stdin são usadas). |
--to-key <key> |
Chave de API do BillionSend como argumento. Mesma ressalva. |
--rps <n> |
Requisições por segundo contra a origem. Padrão 8, até 100. O limite do Resend é 10 e é dividido com o seu envio em produção. Passe de 10 só depois de o Resend aumentar o seu limite. |
--only <a,b> |
Move só estes recursos. |
--skip <a,b> |
Pula estes recursos. |
--on-conflict <mode> |
Para contatos que já existem: upsert (padrão), skip ou error. |
--include-sent |
Importa transmissões já enviadas como rascunhos. Ignoradas por padrão. |
--fresh-webhook-secrets |
Cria novos segredos de assinatura de webhook em vez de copiar os antigos. Mostrados uma única vez, no relatório. |
--fresh |
Esquece o progresso salvo e lê tudo de novo. O que execuções anteriores criaram é mantido, então o rollback continua funcionando. |
--out <file> |
migrate plan: escreve o plano como JSON. |
--report <file> |
Escreve também o relatório em Markdown neste caminho. |
-y, --yes |
Pula as confirmações. |
--non-interactive |
Nunca faz perguntas. Uma entrada faltando termina com 1. Automático quando o stdin não é um terminal, e com --json. |
--json |
JSON no stdout, progresso no stderr. |
-v, --verbose |
Registra cada requisição. |
--color <mode>, --no-color |
auto (padrão), always ou never. |
-h, --help / -V, --version |
Ajuda e versão. |
Os recursos para --only e --skip, na ordem em que são aplicados: domains, properties, topics, segments, contacts, enrichment, broadcasts, templates, webhooks, suppressions, api-keys. enrichment é a segunda etapa, que lê as assinaturas de tópicos e as propriedades de cada contato.
Variáveis de ambiente
| Variável | Significado |
|---|---|
RESEND_API_KEY |
Chave de API de origem, acesso total. |
BILLIONSEND_API_KEY |
Sua chave de API do BillionSend, acesso total. |
BILLIONSEND_BASE_URL |
URL da API do BillionSend, igual a --to-url. |
NO_COLOR |
Desliga as cores. |
FORCE_COLOR |
Cores mesmo em pipe. |
Cada chave é procurada nesta ordem: variável de ambiente, flag -stdin, flag de argumento e, em um terminal, um prompt oculto.
Arquivos
A ferramenta os escreve ao lado de onde você a roda, legíveis só por você e sem nunca conter uma chave:
| Arquivo | Conteúdo |
|---|---|
.billionsend/migrate-state.json |
O que a ferramenta criou e onde parou, para uma execução interrompida continuar. |
.billionsend/migrate-report.json |
O relatório da última execução como dados. |
.billionsend/migrate-report.md |
O mesmo relatório em Markdown: contagens, lista de tarefas, registros DNS por domínio, um mapa de ids (ids de tópicos e segmentos de origem para ids do BillionSend) e itens manuais. |
.billionsend/ é acrescentado ao .gitignore quando há um no diretório atual.
Segurança
- O Resend só é lido. Toda requisição ao Resend é um
GET. As escritas vão só para a sua API do BillionSend. - As chaves ficam na memória e são ocultadas de toda linha de log. Não há telemetria nem verificação de atualização.
- Um
401ou403interrompe a execução. A ferramenta não tenta de novo nem contorna. - Os limites de taxa são respeitados. Em
429ela espera oretry-after. Em erro de servidor ou de rede, tenta até 5 vezes com pausas crescentes. - Os descadastros são mantidos.
unsubscribede as saídas de tópicos são copiados como estão, e ninguém é reinscrito. Veja Marcas e descadastros.
Códigos de saída
| Código | Significado |
|---|---|
0 |
Sucesso, ou, em migrate plan, nada a fazer. |
1 |
Erro: argumentos inválidos, entrada faltando, chave rejeitada. |
2 |
Só em migrate plan: o plano tem mudanças. |
3 |
Parcial: alguns itens falharam. Veja o relatório. |
Scripts e CI
Quando o stdin não é um terminal, ou com --non-interactive ou --json, a ferramenta nunca faz perguntas. Uma entrada faltando termina com 1 e nomeia a variável ou a flag a definir. Passe as chaves por variável de ambiente ou stdin, nunca como argumentos:
export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...
billionsend migrate plan --from resend --out plan.json
# saída 2 significa que há algo a aplicar
billionsend migrate apply plan.json --yes
Com --json, o stdout traz só JSON (o plano em migrate plan, o relatório em migrate apply), então você pode encadeá-lo:
billionsend migrate plan --from resend --json | jq '.counts'
Resend é uma marca registrada da Plus Five Five, Inc. O BillionSend não é afiliado nem endossado pelo Resend.