Bird CLI

bird is de Bird API als opdrachtregel: één binary die verstuurt op elk kanaal dat Bird ondersteunt, die kanalen inricht en de werkruimte eromheen configureert. Het is gebouwd voor twee aanroepers tegelijk: een mens aan een terminal en een agent of script dat het in een lus aanstuurt. Elk commando stuurt standaard JSON naar stdout, schrijft fouten als een gestructureerd foutantwoord naar stderr en sluit af met een semantische code, zodat een consumer vertakt op structuur in plaats van tekst te parsen.

Installeren

macOS en Linux

Homebrew:

Codevoorbeeld

brew install messagebird/tap/bird

Of het installatiescript:

Codevoorbeeld

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

Het script detecteert je platform, verifieert de download en toont waar de binary is geplaatst. Om een release te pinnen of de doelmap te kiezen, geef je de flags door de pipe mee met sh -s --:

Codevoorbeeld

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

Windows

Codevoorbeeld

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

Het installeert naar %LOCALAPPDATA%\bird\bin. Om een release te pinnen of een map te kiezen, download je het script eerst, omdat pipen naar iex geen manier biedt om parameters mee te geven:

Codevoorbeeld

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

Verifieer de installatie op elk platform met bird version.

Authenticeren

Codevoorbeeld

bird auth login --scope emails:write

Dit opent een toestemmingspagina in de browser waar je de gevraagde werkruimte-permissies goedkeurt. Een kale bird auth login vraagt alleen-lezen-toegang aan. De optie --scope emails:write zorgt dat de e-mailverzending in Eerste commando's slaagt. Elk commando dat meer toegang nodig heeft, toont het exacte opnieuw-inlogcommando. De CLI slaat een werkruimte-gebonden OAuth-token op in ~/.config/bird/credentials.json en ververst dit automatisch bij gebruik. Je hoeft geen API-sleutel aan te maken of te kopiëren, en de opgeslagen werkruimteregio maakt het configureren van een host overbodig. Op een headless machine of via SSH toont bird auth login --device een code die je op een ander apparaat goedkeurt in plaats van een lokale browser te openen.

Controleer of de credential werkt:

Codevoorbeeld

bird auth status

auth status rapporteert of een token is geconfigureerd en of het valideert tegen de API, plus de werkruimte, regio en toegekende scopes. Het sluit altijd af met 0, dus vertakt op het veld valid in de JSON-uitvoer. Geef --offline mee om de API-aanroep over te slaan, en bird auth logout om de opgeslagen credential te verwijderen.

Eerste commando's

Verstuur een e-mail en lees deze terug op ID:

Codevoorbeeld

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

De CLI-quickstart doorloopt deze flow van begin tot eind, inclusief het gedeelde onboardingdomein en sandbox-adres van Bird, zodat je kunt versturen voordat je een eigen domein hebt geverifieerd.

Mutaties accepteren invoer op drie manieren, en de inline waarde wint: flags, een JSON-body aangeduid met --body-file <path|-> (- leest stdin), of beide, zodat één opgeslagen template meerdere aanroepen bedient (bird email send --body-file body.json --to x@y.com). De CLI leest nooit stdin waar het niet naar verwezen is. Twee flags maken elke schrijfactie veilig om te oefenen en opnieuw te proberen:

--dry-run toont de opgeloste request-body die verstuurd zou worden en sluit af zonder te verzenden: de verificatiepoort vóór alles wat uitgaat.
--idempotency-key <key> maakt opnieuw proberen veilig: de server speelt het oorspronkelijke antwoord opnieuw af voor elk dubbel verzoek met dezelfde sleutel, hetzelfde idempotentiemechanisme dat de SDK's gebruiken, zodat een netwerk-timeout nooit een dubbele verzending betekent.

Schrijfcommando's ondersteunen ook --example, dat een volledige, geldige request-body toont (gegenereerd uit het API-schema, geen credentials nodig) en afsluit. Destructieve commando's (delete) vereisen een expliciet ID en --yes, zodat een losse retry niet stilletjes state kan vernietigen.

Uitvoercontract

Data gaat naar stdout als JSON zonder dat je een flag nodig hebt; diagnostiek en fouten gaan naar stderr, nooit gemengd met data. Lijsten retourneren een cursor-envelope ({"data": [...], "next_cursor": ...}) met een standaard --limit, zodat uitvoer altijd begrensd is. Pipe naar jq om velden te extraheren (bird email list | jq -r '.data[].id'). Bij single-record-reads (get, show, status) kiest --format text (-f text) voor een leesbare kaart in plaats daarvan.

Fouten zijn een JSON-foutantwoord op stderr met machine-vertakbare velden: code (stabiel ID), type, retryable en retry_after, param en details voor de foutieve invoer, en next met uitvoerbare bird-commando's om te herstellen. API-fouten geven de foutcode, request-ID en docs-link van de server rechtstreeks door. Zie Fouten voor het onderliggende API-foutmodel.

Exitcodes zijn semantisch, zodat een script of agent vertakt zonder tekst te lezen:

Exitcode	Betekenis
0	Succes.
1	Onverwachte / niet-herkende fout. Toon en stop.
2	Ongeldige flags, argumenten of body.
3	Resource niet gevonden.
4	Authenticatie- of autorisatiefout.
5	Conflict of mislukte preconditie.
6	Beperking van het aantal verzoeken of serverfout, opnieuw proberen na retry_after.
7	Een controle heeft een probleem gevonden, bijvoorbeeld bird email templates check.

Commando's melden ontbrekende invoer met exit 2 en een bruikbare hint, zonder interactieve prompt. bird auth login wacht op goedkeuring via de browser of het apparaat. Commando's die wachten op browserbevestiging tonen een reviewlink en confirmation_id in een JSON-melding op stderr. Bewaar het ID voor herstel terwijl het commando wacht op voltooiing. De voorlopige versie van Create Call gebruikt deze flow. Een voltooide bevestiging retourneert het vastgelegde uitvoeringsresultaat. Als de bevestiging verloopt, wordt geannuleerd of eindigt zonder dat resultaat, sluit het commando af met 5. Een ontbrekend resultaat bewijst niet dat de bewerking niet is uitgevoerd. Verifieer de uitkomst voordat je een nieuw verzoek aanmaakt. Als het proces wordt onderbroken, herhaal je het oorspronkelijke commando en de idempotency-sleutel met --confirmation-id <confirmation_id> om te hervatten.

Configuratie

Codevoorbeeld

bird config show

config show toont de opgeloste configuratie: de API-basis-URL en waar die vandaan komt, de config-, cache- en state-paden, en eventuele actieve kanaalstandaarden. De basis-URL wordt in volgorde opgelost: de globale flag --base-url, de omgevingsvariabele BIRD_API_URL, en dan de regio die bij je login is vastgelegd ({region}.platform.bird.com). Na bird auth login hoef je de opgeloste regio normaal niet te overschrijven. De CLI volgt XDG-paden (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); stel BIRD_CONFIG_DIR in om alle drie onder één root samen te voegen, handig voor geïsoleerde CI- of agent-sandboxes.

Twee globale flags werken bij elk commando:

--format (-f): json (standaard) of text (alleen single-record-reads).
--base-url: overschrijf het API-endpoint voor één aanroep, equivalent aan BIRD_API_URL.

Kanaalstandaarden

Voer bird config show uit en gebruik het bestand dat als paths.config_file wordt gemeld voor waarden die je anders bij elke verzending zou herhalen. Dit pad volgt BIRD_CONFIG_DIR en XDG-configuratielocaties. Een geconfigureerde standaard vult het overeenkomstige veld van een verzending die het leeg laat, en een waarde die je bij de aanroep meegeeft wint altijd:

Codevoorbeeld

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

Het email-object accepteert from, reply_to, category, track_opens, track_clicks, headers, tags, metadata en ip_pool_id, en is van toepassing op bird email send, bird email send-batch en bird email mailboxes compose. Elke waarde wordt geschreven zoals de bijbehorende flag: een adres is een gewone of Name <addr>-string, en headers en tags zijn name: value-objecten. Een compose leest alleen reply_to, category, tags en metadata, omdat het verstuurt als de mailbox. Dit zijn dezelfde standaarden die de SDK's accepteren bij clientconstructie, zodat een script en zijn SDK-equivalent vanaf hetzelfde adres versturen. Een sleutel die het bestand niet herkent, wordt bij naam geweigerd in plaats van geparst tot een standaard die nooit van toepassing is. Alleen de commando's die standaarden lezen falen erop; bird config show meldt dezelfde fout, zodat je de typefout kunt vinden.

Ontdek het oppervlak

Codevoorbeeld

bird commands

Dit toont de volledige commandoboom als JSON, inclusief het doel, de flags, verplichte positionele argumenten en het foutcontract van elk commando. Een agent kan het volledige oppervlak in één aanroep opsommen in plaats van --help te scrapen. Gebruik --example of --help om een commando te inspecteren, en dan --dry-run om een preview te zien. Voor veilig opnieuw proberen voer je het commando uit met --idempotency-key. Shell-completion is beschikbaar via bird completion bash|zsh|fish.

Veelgebruikte commandogroepen

De groepen die je het eerst gebruikt. De CLI dekt veel meer (SMS, WhatsApp, Verify, contacten, audiences, billing, supporttickets en meer); voer bird commands uit voor de volledige boom.

bird auth: login, status, logout: beheer de OAuth-credential.
bird email: send, get, list: verstuur berichten en volg hun bezorgstatus.
bird email templates: create, get, list, update, delete, duplicate, preview: maak herbruikbare templates. versions submit bevriest een concept en maakt het de versie die verzendingen gebruiken; versions languages set bewerkt de taalspecifieke inhoud.
bird email domains: create, get, list, verify: registreer verzenddomeinen en controleer DNS-verificatie.
bird email inbound-addresses: create, get, list, update, delete: maak en beheer de doorstuurder-adressen waarop Bird mail ontvangt.
bird email inbound-messages: list, get, body, attachments: lees de mail die Bird heeft ontvangen.
bird webhooks: create, get, list, test, delete: beheer webhook-endpoints en verstuur testleveringen.

Volgende stappen

CLI-quickstart: installeer, log in en verstuur je eerste e-mail in twee minuten.
De CLI voor agents: het volledige agentcontract: JSON-uitvoer, exitcodes, --dry-run, foutantwoord en discovery.
SDK's: hetzelfde API-oppervlak als getypte bibliotheken voor TypeScript, Go en Python.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Ontvang een implementatieoverzicht