Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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
  • 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.

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.

¿Te ha resultado útil esta página?