Bird CLI

bird est l'Bird API en ligne de commande : un seul binaire qui envoie sur chaque canal géré par Bird, configure ces canaux et paramètre l'espace de travail autour d'eux. Il est conçu pour deux appelants à la fois : un humain dans un terminal, et un agent ou script qui le pilote en boucle. Chaque commande émet du JSON sur stdout par défaut, écrit les erreurs sous forme de réponse d'erreur structurée sur stderr, et se termine avec un code sémantique ; un consommateur branche donc sur la structure plutôt que d'analyser du texte.

Installation

macOS et Linux

Homebrew :

Exemple de code

brew install messagebird/tap/bird

Ou le script d'installation :

Exemple de code

curl -fsSL https://cli.bird.com/install.sh | sh

Le script détecte votre plateforme, vérifie le téléchargement et affiche l'emplacement du binaire. Pour figer une version ou choisir la destination, passez les options à travers le pipe avec sh -s -- :

Exemple de code

curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version 1.2.3 --install-dir /opt/bird/bin

Windows

Exemple de code

irm https://cli.bird.com/install.ps1 | iex

Il s'installe dans %LOCALAPPDATA%\bird\bin. Pour figer une version ou choisir un répertoire, téléchargez d'abord le script, car le piping dans iex ne permet pas de passer des paramètres :

Exemple de code

irm https://cli.bird.com/install.ps1 -OutFile install.ps1
.\install.ps1 -Version 1.2.3 -InstallDir C:\tools\bird

Vérifiez l'installation sur n'importe quelle plateforme avec bird version.

Authentification

Exemple de code

bird auth login --scope emails:write

Cette commande ouvre une page de consentement dans le navigateur où vous approuvez les permissions demandées pour l'espace de travail. Un bird auth login seul demande un accès en lecture seule. L'option --scope emails:write permet à l'envoi d'e-mail dans Premières commandes de réussir. Toute commande nécessitant un accès supérieur affiche la commande exacte de reconnexion. Le CLI stocke un jeton OAuth lié à l'espace de travail dans ~/.config/bird/credentials.json et le rafraîchit automatiquement à l'utilisation. Vous n'avez pas besoin de créer ou de copier une clé API, et la région enregistrée de l'espace de travail supprime le besoin de configurer un hôte. Sur une machine sans écran ou via SSH, bird auth login --device affiche un code que vous approuvez sur un autre appareil au lieu d'ouvrir un navigateur local.

Vérifiez que l'identifiant fonctionne :

Exemple de code

bird auth status

auth status indique si un jeton est configuré et s'il est validé par l'API, ainsi que l'espace de travail, la région et les portées accordées. Il se termine toujours par 0 ; branchez donc sur le champ valid dans sa sortie JSON. Passez --offline pour ignorer l'appel API, et bird auth logout pour supprimer l'identifiant stocké.

Premières commandes

Envoyez un e-mail et relisez-le par ID :

Exemple de code

bird email send --from onboarding@messagebird.dev --to delivered@messagebird.dev --subject "Hello" --html "<p>Hi from the CLI.</p>"
bird email get em_01ky7ma8y2es1s2akzk53tmjn0

Le quickstart CLI détaille ce flux de bout en bout, y compris le domaine d'accueil partagé et l'adresse bac à sable de Bird, pour que vous puissiez envoyer avant de vérifier votre propre domaine.

Les mutations acceptent l'entrée de trois façons, et la valeur en ligne l'emporte : des options, un corps JSON désigné par --body-file <path|-> (- lit stdin), ou les deux, de sorte qu'un seul modèle stocké sert plusieurs appels (bird email send --body-file body.json --to x@y.com). Le CLI ne lit jamais un stdin vers lequel il n'a pas été dirigé. Deux options rendent chaque écriture sûre à répéter et réessayer :

--dry-run affiche le corps de requête résolu qui serait envoyé et se termine sans envoyer : la porte de vérification avant tout envoi sortant.
--idempotency-key <key> rend un réessai sûr : le serveur rejoue la réponse d'origine pour toute requête dupliquée portant la même clé, le même mécanisme d'idempotence qu'utilisent les SDKs, de sorte qu'un délai réseau ne signifie jamais un double envoi.

Les commandes d'écriture supportent aussi --example, qui affiche un corps de requête complet et valide (généré à partir du schéma API, sans identifiants) et se termine. Les commandes destructives (delete) exigent un ID explicite et --yes, de sorte qu'un réessai hasardeux ne peut pas détruire silencieusement un état.

Contrat de sortie

Les données vont sur stdout en JSON sans option nécessaire ; les diagnostics et erreurs vont sur stderr, jamais mélangés aux données. Les listes renvoient une enveloppe à curseur ({"data": [...], "next_cursor": ...}) avec un --limit par défaut, de sorte que la sortie est toujours bornée. Pipez vers jq pour extraire des champs (bird email list | jq -r '.data[].id'). Sur les lectures d'enregistrement unique (get, show, status), --format text (-f text) opte pour une fiche lisible par un humain à la place.

Les échecs sont une réponse d'erreur JSON sur stderr avec des champs exploitables par une machine : code (ID stable), type, retryable et retry_after, param et details pour l'entrée fautive, et next listant des commandes bird exécutables pour récupérer. Les erreurs API transmettent directement le code d'erreur du serveur, l'ID de requête et le lien vers la documentation. Consultez Erreurs pour le modèle d'erreur API sous-jacent.

Les codes de sortie sont sémantiques ; un script ou un agent branche donc sans lire de texte :

Code de sortie	Signification
0	Succès.
1	Erreur inattendue / non reconnue. Signaler et arrêter.
2	Options, arguments ou corps invalides.
3	Ressource introuvable.
4	Échec d'authentification ou d'autorisation.
5	Conflit ou précondition échouée.
6	Limitation du débit ou erreur serveur, réessayer après retry_after.

Les commandes ne demandent jamais de saisie interactive ; un agent ou un job CI ne peut donc pas rester bloqué sur une question non sollicitée. Une entrée manquante échoue immédiatement avec le code de sortie 2 et une indication exploitable. La seule commande bloquante est bird auth login, qui attend l'approbation par navigateur ou appareil, puis expire.

Configuration

Exemple de code

bird config show

config show affiche la configuration résolue : l'URL de base API et sa provenance, les chemins de configuration, de cache et d'état, et les éventuels paramètres par défaut de canal en vigueur. L'URL de base se résout dans l'ordre : l'option globale --base-url, la variable d'environnement BIRD_API_URL, puis la région enregistrée lors de votre connexion ({region}.platform.bird.com). Après bird auth login, la région résolue n'a normalement pas besoin d'être redéfinie. Le CLI suit les chemins XDG (~/.config/bird, ~/.cache/bird, ~/.local/state/bird) ; définissez BIRD_CONFIG_DIR pour regrouper les trois sous une seule racine, utile pour les bacs à sable CI ou agent isolés.

Deux options globales fonctionnent sur chaque commande :

--format (-f) : json (par défaut) ou text (lectures d'enregistrement unique seulement).
--base-url : redéfinir le point de terminaison API pour une invocation, équivalent à BIRD_API_URL.

Paramètres par défaut de canal

Exécutez bird config show et utilisez le fichier indiqué comme paths.config_file pour les valeurs que vous répéteriez sinon à chaque envoi. Ce chemin suit BIRD_CONFIG_DIR et les emplacements de configuration XDG. Un paramètre par défaut configuré remplit le champ correspondant d'un envoi qui ne le définit pas, et une valeur passée à l'appel l'emporte toujours :

Exemple de code

{
  "email": {
    "from": "hello@acme.com",
    "reply_to": ["support@acme.com"],
    "tags": { "team": "growth" },
    "ip_pool_id": "ipp_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

L'objet email accepte from, reply_to, category, track_opens, track_clicks, headers, tags, metadata et ip_pool_id, et s'applique à bird email send, bird email send-batch et bird email mailboxes compose. Chaque valeur s'écrit comme l'option correspondante : une adresse est une chaîne simple ou Name <addr>, et headers et tags sont des objets name: value. Une composition ne lit que reply_to, category, tags et metadata, car elle envoie en tant que boîte aux lettres. Ce sont les mêmes valeurs par défaut que les SDKs acceptent à la construction du client ; un script et son équivalent SDK envoient donc depuis la même adresse. Une clé non reconnue par le fichier est refusée par son nom au lieu d'être silencieusement absorbée dans un paramètre par défaut qui ne s'applique jamais. Seules les commandes qui lisent les paramètres par défaut échouent dessus ; bird config show signale la même erreur à la place, pour que vous puissiez trouver la faute de frappe.

Découvrir la surface

Exemple de code

bird commands

Cette commande affiche l'arbre complet des commandes en JSON, y compris l'objectif, les options, les positionnels requis et le contrat d'erreur de chaque commande. Un agent peut énumérer toute la surface en un seul appel au lieu de parcourir --help. Utilisez --example ou --help pour inspecter une commande, puis --dry-run pour la prévisualiser. Pour des réessais sûrs, exécutez la commande avec --idempotency-key. La complétion shell est disponible via bird completion bash|zsh|fish.

Groupes de commandes courants

Les groupes que vous utiliserez en premier. Le CLI couvre bien plus (SMS, WhatsApp, Verify, contacts, audiences, facturation, tickets de support, et autres) ; exécutez bird commands pour l'arbre complet.

bird auth : login, status, logout : gérer l'identifiant OAuth.
bird email : send, get, list : envoyer des messages et suivre leur statut de livraison.
bird email templates : create, get, list, update, delete, duplicate, preview : créer des modèles réutilisables. versions submit fige un brouillon et en fait la version servie par les envois ; versions languages set modifie son contenu par langue.
bird email domains : create, get, list, verify : enregistrer des domaines d'envoi et vérifier la vérification DNS.
bird email inbound-addresses : create, get, list, update, delete : créer et gérer les adresses de transfert sur lesquelles Bird reçoit du courrier.
bird email inbound-messages : list, get, body, attachments : lire le courrier reçu par Bird.
bird webhooks : create, get, list, test, delete : gérer les points de terminaison webhook et déclencher des livraisons de test.

Étapes suivantes

Quickstart CLI : installer, se connecter et envoyer votre premier e-mail en deux minutes.
Le CLI pour les agents : le contrat agent complet : sortie JSON, codes de sortie, --dry-run, réponse d'erreur et découverte.
SDKs : la même surface API sous forme de bibliothèques typées pour TypeScript, Go et Python.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation