CLI
@billionsend/cli lleva una cuenta de email a BillionSend desde tu terminal.
@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. El paquete es @billionsend/cli en npm y su código fuente está en billionsend/billionsend-cli en GitHub.
Instalar
Necesita Node 18 o superior. Ejecútalo sin instalarlo:
npx @billionsend/cli migrate --from resend
O instálalo una vez:
npm install -g @billionsend/cli
billionsend --version
Comandos
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
migratees 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 planmuestra qué cambiaría y no escribe nada. Antes de cualquier escritura comprueba los límites de tu plan conGET /usagey dice qué no cabe, por ejemplo “7 domains to create; the Free plan allows 3”. También estima el tiempo.migrate applyaplica 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 statusmuestra qué creó la última ejecución y qué queda en la lista de comprobación. No necesita claves.migrate rollbackelimina solo lo que creó esta herramienta, nunca las filas que solo actualizó. Imprime la lista y pregunta antes (--yesse 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
401o un403detiene la ejecución. La herramienta no reintenta ni lo esquiva. - Se respetan los límites de frecuencia. Con
429espera el valor deretry-after. Ante un error de servidor o de red reintenta hasta 5 veces con pausas crecientes. - Las bajas se conservan.
unsubscribedy las bajas de temas se copian tal cual, y nadie vuelve a suscribirse. Consulta Bajas.
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:
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:
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.