---
title: CLI
description: "@billionsend/cli move uma conta de e-mail para o BillionSend pelo seu terminal."
ai:
  exclude: true
---

`@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](/docs/pt-br/migrate-from-resend). O pacote é [`@billionsend/cli` no npm](https://www.npmjs.com/package/@billionsend/cli) e o código-fonte está em [billionsend/billionsend-cli](https://github.com/billionsend/billionsend-cli) no GitHub.

## Instalar

Precisa do Node 18 ou mais novo. Rode sem instalar:

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

Ou instale uma vez:

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

## Comandos

```sh
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](/docs/pt-br/concepts/unsubscribes).

## 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:

```sh
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:

```sh
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.
