CLI
@billionsend/cli migre un compte e-mail vers BillionSend depuis votre terminal.
@billionsend/cli migre un compte e-mail vers BillionSend. Il lit le compte source, le compare au vôtre, applique la différence et écrit un rapport. Resend est aujourd’hui la seule source. Le guide pas à pas se trouve dans Migrer depuis Resend. Le paquet est @billionsend/cli sur npm et son code source est billionsend/billionsend-cli sur GitHub.
Installer
Node 18 ou une version plus récente est nécessaire. Lancez-le sans l’installer :
npx @billionsend/cli migrate --from resend
Ou installez-le une fois pour toutes :
npm install -g @billionsend/cli
billionsend --version
Commandes
billionsend migrate --from resend # se connecter, choisir les ressources, planifier, confirmer, appliquer
billionsend migrate plan --from resend [--out plan.json] # lecture seule : sortie 0 rien à faire, 2 modifications, 1 erreur
billionsend migrate apply [plan.json] [--yes] # appliquer un plan enregistré, ou planifier et appliquer d'un coup
billionsend migrate status # ce que la dernière exécution a créé et ce qu'il reste à faire
billionsend migrate rollback [--yes] # supprimer uniquement ce que cet outil a créé
migrateest le mode interactif. Il demande ce qui manque (les clés), vous laisse choisir les ressources, affiche le plan, demande confirmation, l’applique et affiche un résumé.migrate planmontre ce qui changerait et n’écrit rien. Avant toute écriture, il vérifie les limites de votre forfait avecGET /usageet indique ce qui ne rentre pas, par exemple7 domains to create; the Free plan allows 3. Il estime aussi la durée.migrate applyapplique un plan enregistré, ou planifie et applique en une seule fois. Les contacts sont rapprochés par adresse e-mail. Tout le reste est rapproché par nom, clé, point de terminaison ou alias, puis mis à jour s’il diffère et laissé tel quel s’il est identique.migrate statusmontre ce que la dernière exécution a créé et ce qu’il reste sur la liste de contrôle. Il n’a besoin d’aucune clé.migrate rollbacksupprime uniquement ce que cet outil a créé, jamais les lignes qu’il a seulement mises à jour. Il affiche la liste et demande confirmation avant (--yessaute la question).
Options
| Option | Signification |
|---|---|
--from <provider> |
Fournisseur source. Uniquement resend. |
--from-key-stdin |
Lit la clé d’API source sur stdin (première ligne). |
--from-key <key> |
Clé d’API source passée en argument. Elle est visible dans la liste des processus ; préférez donc la variable d’environnement. |
--to-url <url> |
URL de l’API BillionSend. Par défaut https://api.billionsend.com. |
--to-key-stdin |
Lit la clé d’API BillionSend sur stdin (deuxième ligne quand les deux options stdin sont utilisées). |
--to-key <key> |
Clé d’API BillionSend passée en argument. Même réserve. |
--rps <n> |
Requêtes par seconde vers la source. Par défaut 8, jusqu’à 100. La limite de Resend est de 10 et elle est partagée avec votre envoi en production. Ne dépassez 10 qu’après que Resend a relevé votre limite. |
--only <a,b> |
Ne migre que ces ressources. |
--skip <a,b> |
Ignore ces ressources. |
--on-conflict <mode> |
Pour les contacts qui existent déjà : upsert (par défaut), skip ou error. |
--include-sent |
Importe les campagnes déjà envoyées comme brouillons. Ignorées par défaut. |
--fresh-webhook-secrets |
Crée de nouveaux secrets de signature de webhook au lieu de copier les anciens. Affichés une seule fois, dans le rapport. |
--fresh |
Oublie la progression enregistrée et relit tout. Ce que les exécutions précédentes ont créé est conservé, donc rollback fonctionne toujours. |
--out <file> |
migrate plan : écrit le plan au format JSON. |
--report <file> |
Écrit aussi le rapport Markdown à cet emplacement. |
-y, --yes |
Saute les confirmations. |
--non-interactive |
Ne pose jamais de questions. Une entrée manquante se termine avec le code 1. Automatique quand stdin n’est pas un terminal, et avec --json. |
--json |
JSON sur stdout, progression sur stderr. |
-v, --verbose |
Journalise chaque requête. |
--color <mode>, --no-color |
auto (par défaut), always ou never. |
-h, --help / -V, --version |
Aide et version. |
Les ressources pour --only et --skip, dans l’ordre où elles sont appliquées : domains, properties, topics, segments, contacts, enrichment, broadcasts, templates, webhooks, suppressions, api-keys. enrichment est la seconde passe, qui lit les abonnements aux thématiques et les propriétés de chaque contact.
Variables d’environnement
| Variable | Signification |
|---|---|
RESEND_API_KEY |
Clé d’API source, accès complet. |
BILLIONSEND_API_KEY |
Votre clé d’API BillionSend, accès complet. |
BILLIONSEND_BASE_URL |
URL de l’API BillionSend, identique à --to-url. |
NO_COLOR |
Désactive les couleurs. |
FORCE_COLOR |
Couleurs même quand la sortie passe par un tube. |
Chaque clé est cherchée dans cet ordre : variable d’environnement, option -stdin, option d’argument, puis, dans un terminal, une invite masquée.
Fichiers
L’outil les écrit à côté de l’endroit où vous le lancez, lisibles par vous seul et sans jamais contenir de clé :
| Fichier | Contenu |
|---|---|
.billionsend/migrate-state.json |
Ce que l’outil a créé et où il s’est arrêté, pour qu’une exécution interrompue reprenne. |
.billionsend/migrate-report.json |
Le rapport de la dernière exécution sous forme de données. |
.billionsend/migrate-report.md |
Le même rapport en Markdown : totaux, liste de contrôle, enregistrements DNS par domaine, une table de correspondance des identifiants (identifiants de thématiques et de segments source vers identifiants BillionSend) et éléments manuels. |
.billionsend/ est ajouté à .gitignore quand le répertoire courant en contient un.
Sécurité
- Resend n’est que lu. Chaque requête vers Resend est un
GET. Les écritures vont uniquement vers votre API BillionSend. - Les clés restent en mémoire et sont masquées dans chaque ligne de journal. Il n’y a ni télémétrie ni vérification de mise à jour.
- Un
401ou un403arrête l’exécution. L’outil ne réessaie pas et ne contourne pas l’erreur. - Les limites de débit sont respectées. Sur un
429, il attend la durée deretry-after. Sur une erreur serveur ou réseau, il réessaie jusqu’à 5 fois avec des pauses de plus en plus longues. - Les désinscriptions sont conservées.
unsubscribedet les désinscriptions de thématiques sont copiées telles quelles, et personne n’est réinscrit. Consultez Désinscriptions.
Codes de sortie
| Code | Signification |
|---|---|
0 |
Succès, ou, pour migrate plan, rien à faire. |
1 |
Erreur : arguments incorrects, entrée manquante, clé refusée. |
2 |
migrate plan uniquement : le plan contient des modifications. |
3 |
Partiel : certains éléments ont échoué. Consultez le rapport. |
Scripts et CI
Quand stdin n’est pas un terminal, ou avec --non-interactive ou --json, l’outil ne pose jamais de questions. Une entrée manquante se termine avec le code 1 et nomme la variable ou l’option à définir. Passez les clés par variable d’environnement ou par stdin, jamais en arguments :
export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...
billionsend migrate plan --from resend --out plan.json
# la sortie 2 signifie qu'il y a quelque chose à appliquer
billionsend migrate apply plan.json --yes
Avec --json, stdout ne contient que du JSON (le plan pour migrate plan, le rapport pour migrate apply), ce qui permet de l’enchaîner dans un tube :
billionsend migrate plan --from resend --json | jq '.counts'
Resend est une marque déposée de Plus Five Five, Inc. BillionSend n’est ni affilié à Resend ni approuvé par Resend.