---
title: CLI
description: "@billionsend/cli lleva una cuenta de email a BillionSend desde tu terminal."
seo:
  title: "CLI de email: migra tu cuenta"
ai:
  exclude: true
---

`@billionsend/cli` lleva una cuenta de email a BillionSend. Lee la cuenta de origen, la compara con la tuya, aplica la diferencia y escribe un informe. Hoy el único origen es Resend. La guía paso a paso está en [Migrar desde Resend](/docs/es/migrate-from-resend). El paquete es [`@billionsend/cli` en npm](https://www.npmjs.com/package/@billionsend/cli) y su código fuente está en [billionsend/billionsend-cli](https://github.com/billionsend/billionsend-cli) en GitHub.

## Instalar

Necesita Node 18 o superior. Ejecútalo sin instalarlo:

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

O instálalo una vez:

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

## Comandos

```sh
billionsend migrate --from resend                          # conectar, elegir recursos, planificar, confirmar, aplicar
billionsend migrate plan --from resend [--out plan.json]   # solo lectura: salida 0 nada que hacer, 2 cambios, 1 error
billionsend migrate apply [plan.json] [--yes]              # aplicar un plan guardado, o planificar y aplicar de una vez
billionsend migrate status                                 # qué creó la última ejecución y qué queda
billionsend migrate rollback [--yes]                       # eliminar solo lo que creó esta herramienta
```

- **`migrate`** es el camino interactivo. Pide lo que falta (claves), te deja elegir recursos, muestra el plan, pide confirmación, lo aplica e imprime un resumen.
- **`migrate plan`** muestra qué cambiaría y no escribe nada. Antes de cualquier escritura comprueba los límites de tu plan con `GET /usage` y dice qué no cabe, por ejemplo "7 domains to create; the Free plan allows 3". También estima el tiempo.
- **`migrate apply`** aplica un plan guardado, o planifica y aplica de una vez. Los contactos se emparejan por email. Todo lo demás se empareja por nombre, clave, endpoint o alias, y se actualiza si es distinto y se deja igual si coincide.
- **`migrate status`** muestra qué creó la última ejecución y qué queda en la lista de comprobación. No necesita claves.
- **`migrate rollback`** elimina solo lo que creó esta herramienta, nunca las filas que solo actualizó. Imprime la lista y pregunta antes (`--yes` se salta la pregunta).

## Opciones

| Opción | Significado |
| --- | --- |
| `--from <provider>` | Proveedor de origen. Solo `resend`. |
| `--from-key-stdin` | Lee la clave de API de origen desde stdin (primera línea). |
| `--from-key <key>` | Clave de API de origen como argumento. Se ve en la lista de procesos, así que es mejor usar la variable de entorno. |
| `--to-url <url>` | URL de la API de BillionSend. Por defecto `https://api.billionsend.com`. |
| `--to-key-stdin` | Lee la clave de API de BillionSend desde stdin (segunda línea cuando se usan las dos opciones de stdin). |
| `--to-key <key>` | Clave de API de BillionSend como argumento. Misma advertencia. |
| `--rps <n>` | Solicitudes por segundo contra el origen. Por defecto 8, hasta 100. El límite de Resend es 10 y se comparte con tu envío en producción. Pasa de 10 solo después de que Resend suba tu límite. |
| `--only <a,b>` | Mueve solo estos recursos. |
| `--skip <a,b>` | Omite estos recursos. |
| `--on-conflict <mode>` | Para contactos que ya existen: `upsert` (por defecto), `skip` o `error`. |
| `--include-sent` | Importa los envíos masivos ya enviados como borradores. Se omiten por defecto. |
| `--fresh-webhook-secrets` | Crea secretos de firma de webhook nuevos en lugar de copiar los antiguos. Se muestran una sola vez, en el informe. |
| `--fresh` | Olvida el progreso guardado y lo vuelve a leer todo. Lo que crearon las ejecuciones anteriores se conserva, así que `rollback` sigue funcionando. |
| `--out <file>` | `migrate plan`: escribe el plan como JSON. |
| `--report <file>` | Escribe además el informe en Markdown en esta ruta. |
| `-y`, `--yes` | Se salta las confirmaciones. |
| `--non-interactive` | No hace preguntas nunca. Si falta un dato, termina con 1. Es automático cuando stdin no es un terminal, y con `--json`. |
| `--json` | JSON en stdout, progreso en stderr. |
| `-v`, `--verbose` | Registra cada solicitud. |
| `--color <mode>`, `--no-color` | `auto` (por defecto), `always` o `never`. |
| `-h`, `--help` / `-V`, `--version` | Ayuda y versión. |

Recursos para `--only` y `--skip`, en el orden en que se aplican: `domains`, `properties`, `topics`, `segments`, `contacts`, `enrichment`, `broadcasts`, `templates`, `webhooks`, `suppressions`, `api-keys`. `enrichment` es la segunda pasada que lee las suscripciones a temas y las propiedades de cada contacto.

## Variables de entorno

| Variable | Significado |
| --- | --- |
| `RESEND_API_KEY` | Clave de API de origen, con acceso total. |
| `BILLIONSEND_API_KEY` | Tu clave de API de BillionSend, con acceso total. |
| `BILLIONSEND_BASE_URL` | URL de la API de BillionSend, igual que `--to-url`. |
| `NO_COLOR` | Desactiva los colores. |
| `FORCE_COLOR` | Colores incluso con redirección. |

Cada clave se busca en este orden: variable de entorno, opción `-stdin`, opción como argumento y, en un terminal, una pregunta oculta.

## Archivos

La herramienta escribe estos archivos junto al lugar donde la ejecutas, legibles solo por ti y sin ninguna clave dentro:

| Archivo | Contenido |
| --- | --- |
| `.billionsend/migrate-state.json` | Lo que creó la herramienta y dónde se detuvo, para que una ejecución interrumpida se reanude. |
| `.billionsend/migrate-report.json` | El informe de la última ejecución como datos. |
| `.billionsend/migrate-report.md` | El mismo informe en Markdown: recuentos, lista de comprobación, registros DNS por dominio, un mapa de ids (ids de temas y segmentos de origen a ids de BillionSend) y tareas manuales. |

`.billionsend/` se añade a `.gitignore` cuando hay uno en el directorio actual.

## Seguridad

- **Resend solo se lee.** Toda solicitud a Resend es un `GET`. Las escrituras van solo a tu API de BillionSend.
- **Las claves se quedan en memoria** y se ocultan en todas las líneas de registro. No hay telemetría ni comprobación de actualizaciones.
- **Un `401` o un `403` detiene la ejecución.** La herramienta no reintenta ni lo esquiva.
- **Se respetan los límites de frecuencia.** Con `429` espera el valor de `retry-after`. Ante un error de servidor o de red reintenta hasta 5 veces con pausas crecientes.
- **Las bajas se conservan.** `unsubscribed` y las bajas de temas se copian tal cual, y nadie vuelve a suscribirse. Consulta [Bajas](/docs/es/concepts/unsubscribes).

## Códigos de salida

| Código | Significado |
| --- | --- |
| `0` | Éxito o, en `migrate plan`, nada que hacer. |
| `1` | Error: argumentos incorrectos, dato que falta, clave rechazada. |
| `2` | Solo `migrate plan`: el plan tiene cambios. |
| `3` | Parcial: algunos elementos fallaron. Consulta el informe. |

## Scripts y CI

Cuando stdin no es un terminal, o con `--non-interactive` o `--json`, la herramienta no hace preguntas. Si falta un dato, termina con 1 e indica la variable u opción que hay que definir. Pasa las claves por variable de entorno o por stdin, nunca como argumentos:

```sh
export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...

billionsend migrate plan --from resend --out plan.json
# la salida 2 significa que hay algo que aplicar
billionsend migrate apply plan.json --yes
```

Con `--json`, stdout lleva solo JSON (el plan en `migrate plan`, el informe en `migrate apply`) para que puedas encadenarlo con otro comando:

```sh
billionsend migrate plan --from resend --json | jq '.counts'
```

---

Resend es una marca registrada de Plus Five Five, Inc. BillionSend no está afiliado a Resend ni cuenta con su respaldo.
