Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

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 plan mostra o que mudaria e não escreve nada. Antes de qualquer escrita, ele confere os limites do seu plano por GET /usage e diz o que não cabe, por exemplo “7 domains to create; the Free plan allows 3”. Também estima o tempo.
  • migrate apply aplica 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 status mostra o que a última execução criou e o que resta na lista de tarefas. Não precisa de chaves.
  • migrate rollback apaga só o que esta ferramenta criou, nunca linhas que ela apenas atualizou. Ele imprime a lista e pergunta antes (--yes pula 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 401 ou 403 interrompe a execução. A ferramenta não tenta de novo nem contorna.
  • Os limites de taxa são respeitados. Em 429 ela espera o retry-after. Em erro de servidor ou de rede, tenta até 5 vezes com pausas crescentes.
  • Os descadastros são mantidos. unsubscribed e 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.

Esta página foi útil?