Bird CLI

bird ist die Bird API als Kommandozeile: eine einzelne Binary, die auf jedem Kanal sendet, den Bird betreibt, diese Kanäle einrichtet und den Workspace darum herum konfiguriert. Sie ist für zwei Aufrufer gleichzeitig gebaut: einen Menschen am Terminal und einen Agenten oder ein Skript, das sie in einer Schleife steuert. Jeder Befehl gibt standardmäßig JSON auf stdout aus, schreibt Fehler als strukturierte Fehlerantwort auf stderr und beendet sich mit einem semantischen Code, sodass ein Konsument anhand der Struktur verzweigt statt Prosa zu parsen.

Installation

macOS und Linux

Homebrew:

Codebeispiel

brew install messagebird/tap/bird

Oder das Installationsskript:

Codebeispiel

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

Das Skript erkennt Ihre Plattform, verifiziert den Download und gibt aus, wo die Binary gelandet ist. Um ein Release zu pinnen oder das Zielverzeichnis zu wählen, übergeben Sie die Flags über die Pipe mit sh -s --:

Codebeispiel

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

Windows

Codebeispiel

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

Es installiert nach %LOCALAPPDATA%\bird\bin. Um ein Release zu pinnen oder ein Verzeichnis zu wählen, laden Sie das Skript zuerst herunter, weil Piping in iex keine Möglichkeit lässt, Parameter zu übergeben:

Codebeispiel

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

Überprüfen Sie die Installation auf jeder Plattform mit bird version.

Authentifizierung

Codebeispiel

bird auth login --scope emails:write

Dies öffnet eine Browser-Zustimmungsseite, auf der Sie die angeforderten Workspace-Berechtigungen genehmigen. Ein bloßes bird auth login fordert Lesezugriff an. Die Option --scope emails:write lässt den E-Mail-Versand unter Erste Befehle gelingen. Jeder Befehl, der mehr Zugriff benötigt, gibt den genauen Re-Login-Befehl aus. CLI speichert ein Workspace-gebundenes OAuth-Token in ~/.config/bird/credentials.json und aktualisiert es bei Verwendung automatisch. Sie müssen keinen API-Schlüssel erstellen oder kopieren, und die gespeicherte Workspace-Region macht die Konfiguration eines Hosts überflüssig. Auf einer Maschine ohne Display oder über SSH gibt bird auth login --device einen Code aus, den Sie auf einem anderen Gerät bestätigen, statt einen lokalen Browser zu öffnen.

Prüfen Sie, ob die Anmeldedaten funktionieren:

Codebeispiel

bird auth status

auth status meldet, ob ein Token konfiguriert ist und ob es sich gegen die API validieren lässt, samt Workspace, Region und gewährten Scopes. Der Befehl beendet sich immer mit 0; verzweigen Sie daher auf das Feld valid in seiner JSON-Ausgabe. Übergeben Sie --offline, um den API-Aufruf zu überspringen, und bird auth logout, um die gespeicherten Anmeldedaten zu verwerfen.

Erste Befehle

Senden Sie eine E-Mail und lesen Sie sie anhand der ID zurück:

Codebeispiel

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

Der CLI-Schnellstart führt diesen Ablauf vollständig durch, einschließlich der gemeinsamen Onboarding-Domain und Sandbox-Adresse von Bird, sodass Sie senden können, bevor Sie eine eigene Domain verifiziert haben.

Mutationen nehmen Eingaben auf drei Wegen entgegen, wobei der Inline-Wert gewinnt: Flags, ein JSON-Body benannt durch --body-file <path|-> (- liest stdin), oder beides, sodass ein gespeichertes Template viele Aufrufe bedient (bird email send --body-file body.json --to x@y.com). CLI liest niemals stdin, auf das es nicht verwiesen wurde. Zwei Flags machen jeden Schreibvorgang sicher zum Probelauf und zur Wiederholung:

--dry-run gibt den aufgelösten Request-Body aus, der gesendet würde, und beendet sich ohne zu senden: das Prüftor vor allem Ausgehenden.
--idempotency-key <key> macht eine Wiederholung sicher: Der Server spielt die ursprüngliche Antwort für jede doppelte Anfrage mit demselben Schlüssel erneut ab, derselbe Idempotenz-Mechanismus, den die SDKs verwenden, sodass ein Netzwerk-Timeout nie einen doppelten Versand bedeutet.

Schreibbefehle unterstützen auch --example, das einen vollständigen, gültigen Request-Body ausgibt (generiert aus dem API-Schema, keine Anmeldedaten nötig) und sich beendet. Destruktive Befehle (delete) erfordern eine explizite ID und --yes, damit eine unkontrollierte Wiederholung nicht stillschweigend Zustand zerstört.

Ausgabevertrag

Daten gehen ohne nötiges Flag als JSON auf stdout; Diagnosen und Fehler gehen auf stderr, nie mit Daten vermischt. Listen liefern eine Cursor-Hülle ({"data": [...], "next_cursor": ...}) mit einem Standard---limit, sodass die Ausgabe immer begrenzt ist. Pipen Sie zu jq, um Felder zu extrahieren (bird email list | jq -r '.data[].id'). Bei Einzeldatensatz-Abfragen (get, show, status) wechselt --format text (-f text) zu einer menschenlesbaren Kartenansicht.

Fehler sind eine JSON-Fehlerantwort auf stderr mit maschinell auswertbaren Feldern: code (stabile ID), type, retryable und retry_after, param und details für die fehlerhafte Eingabe, sowie next mit ausführbaren bird-Befehlen zur Wiederherstellung. API-Fehler reichen den Fehlercode, die Request-ID und den Docs-Link des Servers direkt durch. Siehe Fehler für das zugrunde liegende API-Fehlermodell.

Exit-Codes sind semantisch, sodass ein Skript oder Agent verzweigt, ohne Text lesen zu müssen:

Exit-Code	Bedeutung
0	Erfolg.
1	Unerwarteter / unbekannter Fehler. Ausgeben und stoppen.
2	Ungültige Flags, Argumente oder Body.
3	Ressource nicht gefunden.
4	Authentifizierungs- oder Autorisierungsfehler.
5	Konflikt oder fehlgeschlagene Vorbedingung.
6	Anfragelimit oder Serverfehler, erneut versuchen nach retry_after.

Befehle fragen nie interaktiv nach, sodass ein Agent oder CI-Job nicht an einer Frage hängen bleibt, die er nicht gestellt hat; fehlende Eingaben schlagen sofort mit Exit 2 und einem verwertbaren Hinweis fehl. Der einzige blockierende Befehl ist bird auth login, der auf Browser- oder Geräte-Genehmigung wartet und dann ein Timeout auslöst.

Konfiguration

Codebeispiel

bird config show

config show gibt die aufgelöste Konfiguration aus: die API-Basis-URL und woher sie stammt, die Config-, Cache- und State-Pfade sowie alle aktiven Kanal-Defaults. Die Basis-URL wird in dieser Reihenfolge aufgelöst: das globale Flag --base-url, die Umgebungsvariable BIRD_API_URL, dann die beim Login gespeicherte Region ({region}.platform.bird.com). Nach bird auth login braucht die aufgelöste Region normalerweise kein Override. CLI folgt XDG-Pfaden (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); setzen Sie BIRD_CONFIG_DIR, um alle drei unter einem Root zusammenzufassen, nützlich für isolierte CI- oder Agent-Sandboxes.

Zwei globale Flags funktionieren bei jedem Befehl:

--format (-f): json (Standard) oder text (nur bei Einzeldatensatz-Abfragen).
--base-url: den API-Endpunkt für einen Aufruf überschreiben, äquivalent zu BIRD_API_URL.

Kanal-Defaults

Führen Sie bird config show aus und verwenden Sie die als paths.config_file gemeldete Datei für Werte, die Sie sonst bei jedem Senden wiederholen würden. Dieser Pfad folgt BIRD_CONFIG_DIR und XDG-Konfigurationsorten. Ein konfigurierter Default füllt das passende Feld eines Sendevorgangs, der es leer lässt, und ein beim Aufruf übergebener Wert gewinnt immer:

Codebeispiel

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

Das email-Objekt nimmt from, reply_to, category, track_opens, track_clicks, headers, tags, metadata und ip_pool_id entgegen und gilt für bird email send, bird email send-batch und bird email mailboxes compose. Jeder Wert wird so geschrieben wie das zugehörige Flag: Eine Adresse ist ein einfacher oder Name <addr>-String, und headers und tags sind name: value-Objekte. Ein Compose liest nur reply_to, category, tags und metadata, weil es als die Mailbox sendet. Das sind dieselben Defaults, die die SDKs bei der Client-Konstruktion akzeptieren, sodass ein Skript und sein SDK-Äquivalent von derselben Adresse senden. Ein Schlüssel, den die Datei nicht erkennt, wird namentlich abgelehnt, statt in einen Default geparst zu werden, der nie greift. Nur die Befehle, die Defaults lesen, scheitern daran; bird config show meldet denselben Fehler stattdessen, sodass Sie den Tippfehler finden können.

Oberfläche erkunden

Codebeispiel

bird commands

Dies gibt den gesamten Befehlsbaum als JSON aus, einschließlich Zweck, Flags, erforderlichen Positionsargumenten und Fehlervertrag jedes Befehls. Ein Agent kann die gesamte Oberfläche in einem Aufruf enumerieren, statt --help zu scrapen. Verwenden Sie --example oder --help, um einen Befehl zu inspizieren, dann --dry-run für eine Vorschau. Für sichere Wiederholungen führen Sie den Befehl mit --idempotency-key aus. Shell-Completion ist über bird completion bash|zsh|fish verfügbar.

Häufige Befehlsgruppen

Die Gruppen, die Sie zuerst verwenden werden. CLI deckt weit mehr ab (SMS, WhatsApp, Verify, Kontakte, Audiences, Billing, Support-Tickets und anderes); führen Sie bird commands für den vollständigen Baum aus.

bird auth: login, status, logout: die OAuth-Anmeldedaten verwalten.
bird email: send, get, list: Nachrichten senden und ihren Zustellstatus verfolgen.
bird email templates: create, get, list, update, delete, duplicate, preview: wiederverwendbare Templates erstellen. versions submit friert einen Entwurf ein und macht ihn zur Version, die Sendevorgänge ausliefern; versions languages set bearbeitet den sprachspezifischen Inhalt.
bird email domains: create, get, list, verify: Sende-Domains registrieren und DNS-Verifizierung prüfen.
bird email inbound-addresses: create, get, list, update, delete: die Weiterleitungsadressen erstellen und verwalten, unter denen Bird E-Mails empfängt.
bird email inbound-messages: list, get, body, attachments: die von Bird empfangene Post lesen.
bird webhooks: create, get, list, test, delete: Webhook-Endpunkte verwalten und Testzustellungen auslösen.

Nächste Schritte

CLI-Schnellstart: installieren, einloggen und Ihre erste E-Mail in zwei Minuten senden.
CLI für Agenten: der vollständige Agent-Vertrag: JSON-Ausgabe, Exit-Codes, --dry-run, Fehlerantwort und Discovery.
SDKs: dieselbe API-Oberfläche als typisierte Bibliotheken für TypeScript, Go und Python.

Verwandte Ressourcen