Bird CLI

bird è l'Bird API come riga di comando: un singolo binario che invia su ogni canale gestito da Bird, configura quei canali e imposta lo spazio di lavoro attorno a essi. È pensato per due tipi di chiamante contemporaneamente: una persona al terminale e un agente o script che lo guida in un ciclo. Ogni comando emette JSON su stdout per impostazione predefinita, scrive gli errori come risposta strutturata su stderr e termina con un codice semantico, così un consumatore ramifica in base alla struttura anziché analizzare testo libero.

Installazione

macOS e Linux

Homebrew:

Esempio di codice

brew install messagebird/tap/bird

Oppure lo script di installazione:

Esempio di codice

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

Lo script rileva la piattaforma, verifica il download e stampa la posizione del binario. Per fissare una release o scegliere la destinazione, passa i flag attraverso la pipe con sh -s --:

Esempio di codice

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

Windows

Esempio di codice

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

Viene installato in %LOCALAPPDATA%\bird\bin. Per fissare una release o scegliere una directory, scarica prima lo script, perché il piping in iex non consente di passare parametri:

Esempio di codice

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

Verifica l'installazione su qualsiasi piattaforma con bird version.

Autenticazione

Esempio di codice

bird auth login --scope emails:write

Questo apre una pagina di consenso nel browser dove approvi i permessi richiesti per lo spazio di lavoro. Un semplice bird auth login richiede accesso in sola lettura. L'opzione --scope emails:write permette all'invio email in Primi comandi di riuscire. Qualsiasi comando che richiede più accesso stampa il comando esatto di re-login. CLI salva un token OAuth legato allo spazio di lavoro in ~/.config/bird/credentials.json e lo rinnova automaticamente a ogni utilizzo. Non serve creare o copiare una chiave API, e la regione registrata dello spazio di lavoro elimina la necessità di configurare un host. Su una macchina headless o via SSH, bird auth login --device stampa un codice che approvi su un altro dispositivo anziché aprire un browser locale.

Verifica che la credenziale funzioni:

Esempio di codice

bird auth status

auth status indica se un token è configurato e se viene validato rispetto all'API, oltre allo spazio di lavoro, alla regione e agli scope concessi. Termina sempre con 0, quindi ramifica sul campo valid nel suo output JSON. Passa --offline per saltare la chiamata API e bird auth logout per eliminare la credenziale salvata.

Primi comandi

Invia un'email e rileggila per ID:

Esempio di codice

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

Il quickstart CLI illustra questo flusso dall'inizio alla fine, inclusi il dominio di onboarding condiviso e l'indirizzo sandbox di Bird, così puoi inviare prima di verificare un tuo dominio.

Le mutazioni accettano input in tre modi, e il valore inline ha la precedenza: flag, un body JSON indicato da --body-file <path|-> (- legge stdin), o entrambi, così un unico template salvato serve più chiamate (bird email send --body-file body.json --to x@y.com). CLI non legge mai stdin a meno che non sia stato puntato. Due flag rendono ogni scrittura sicura da provare e riprovare:

--dry-run stampa il body della richiesta risolto che verrebbe inviato e termina senza inviare: il controllo di verifica prima di qualsiasi operazione in uscita.
--idempotency-key <key> rende sicuro riprovare: il server riproduce la risposta originale per qualsiasi richiesta duplicata con la stessa chiave, lo stesso meccanismo di idempotenza usato dagli SDK, così un timeout di rete non significa mai un doppio invio.

I comandi di scrittura supportano anche --example, che stampa un body di richiesta completo e valido (generato dallo schema API, senza bisogno di credenziali) e termina. I comandi distruttivi (delete) richiedono un ID esplicito e --yes, così un tentativo ripetuto non distrugge silenziosamente lo stato.

Contratto di output

I dati vanno su stdout come JSON senza bisogno di flag; diagnostica ed errori vanno su stderr, mai mescolati con i dati. Le liste restituiscono un envelope con cursore ({"data": [...], "next_cursor": ...}) con un --limit predefinito, così l'output è sempre limitato. Fai pipe verso jq per estrarre campi (bird email list | jq -r '.data[].id'). Sulle letture di un singolo record (get, show, status), --format text (-f text) passa a una scheda leggibile invece.

I fallimenti sono un envelope JSON su stderr con campi su cui ramificare programmaticamente: code (ID stabile), type, retryable e retry_after, param e details per l'input incriminato, e next che elenca comandi bird eseguibili per il recupero. Gli errori API passano direttamente il codice di errore del server, l'ID della richiesta e il link alla documentazione. Vedi Errori per il modello di errore API sottostante.

I codici di uscita sono semantici, così uno script o un agente ramifica senza leggere alcun testo:

Codice di uscita	Significato
0	Successo.
1	Errore imprevisto / non riconosciuto. Mostra e ferma.
2	Flag, argomenti o body non validi.
3	Risorsa non trovata.
4	Errore di autenticazione o autorizzazione.
5	Conflitto o precondizione fallita.
6	Limitazione delle richieste o errore del server, riprovare dopo retry_after.
7	Un controllo ha trovato un problema, ad esempio bird email templates check.

I comandi segnalano un input mancante con exit 2 e un suggerimento operativo, senza prompt interattivo. bird auth login attende l'approvazione nel browser o sul dispositivo. I comandi in attesa di conferma nel browser stampano un link di revisione e confirmation_id in un avviso JSON su stderr. Conserva l'ID per il recupero mentre il comando attende il completamento. Il flusso è usato dalla versione in anteprima di Create Call. Una conferma completata restituisce il risultato di esecuzione registrato. Se la conferma scade, viene annullata o termina senza quel risultato, il comando esce con 5. Un risultato mancante non prova che l'operazione non sia stata eseguita. Riconcilia il suo esito prima di creare un'altra richiesta. In caso di interruzione, ripeti il comando originale e la chiave di idempotenza con --confirmation-id <confirmation_id> per riprendere.

Configurazione

Esempio di codice

bird config show

config show stampa la configurazione risolta: il base URL API e la sua provenienza, i percorsi di config, cache e stato, e qualsiasi default di canale attivo. Il base URL si risolve in ordine: il flag globale --base-url, la variabile d'ambiente BIRD_API_URL, quindi la regione registrata con il tuo login ({region}.platform.bird.com). Dopo bird auth login, la regione risolta normalmente non necessita di override. CLI segue i percorsi XDG (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); imposta BIRD_CONFIG_DIR per riunire tutti e tre sotto un'unica radice, utile per sandbox CI o agente isolati.

Due flag globali funzionano su ogni comando:

--format (-f): json (predefinito) o text (solo letture di un singolo record).
--base-url: sovrascrive l'endpoint API per una singola invocazione, equivalente a BIRD_API_URL.

Default di canale

Esegui bird config show e usa il file indicato come paths.config_file per i valori che altrimenti ripeteresti a ogni invio. Questo percorso segue BIRD_CONFIG_DIR e le posizioni di configurazione XDG. Un default configurato popola il campo corrispondente di un invio che lo lascia vuoto, e un valore passato alla chiamata ha sempre la precedenza:

Esempio di codice

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

L'oggetto email accetta from, reply_to, category, track_opens, track_clicks, headers, tags, metadata e ip_pool_id, e si applica a bird email send, bird email send-batch e bird email mailboxes compose. Ogni valore si scrive come il flag corrispondente: un indirizzo è una stringa semplice o Name <addr>, e headers e tags sono oggetti name: value. Un compose legge solo reply_to, category, tags e metadata, perché invia come la casella. Sono gli stessi default che gli SDK accettano alla costruzione del client, così uno script e il suo equivalente SDK inviano dallo stesso indirizzo. Una chiave non riconosciuta dal file viene rifiutata per nome anziché essere analizzata in un default che non si applica mai. Solo i comandi che leggono i default falliscono su di essa; bird config show segnala invece lo stesso errore, così puoi trovare il refuso.

Scoprire la superficie

Esempio di codice

bird commands

Questo stampa l'intero albero dei comandi come JSON, inclusi scopo, flag, argomenti posizionali obbligatori e contratto di errore di ogni comando. Un agente può enumerare l'intera superficie in una sola chiamata anziché fare scraping di --help. Usa --example o --help per ispezionare un comando, quindi --dry-run per visualizzarne l'anteprima. Per ripetizioni sicure, esegui il comando con --idempotency-key. Il completamento della shell è disponibile tramite bird completion bash|zsh|fish.

Gruppi di comandi comuni

I gruppi che userai per primi. CLI copre molto di più (SMS, WhatsApp, Verify, contatti, audience, fatturazione, ticket di supporto e altro); esegui bird commands per l'albero completo.

bird auth: login, status, logout: gestisci la credenziale OAuth.
bird email: send, get, list: invia messaggi e traccia il loro stato di consegna.
bird email templates: create, get, list, update, delete, duplicate, preview: crea template riutilizzabili. versions submit congela una bozza e la rende la versione servita dagli invii; versions languages set ne modifica il contenuto per lingua.
bird email domains: create, get, list, verify: registra domini di invio e controlla la verifica DNS.
bird email inbound-addresses: create, get, list, update, delete: crea e gestisci gli indirizzi di inoltro su cui Bird riceve posta.
bird email inbound-messages: list, get, body, attachments: leggi la posta ricevuta da Bird.
bird webhooks: create, get, list, test, delete: gestisci endpoint webhook e lancia consegne di test.

Passi successivi

Quickstart CLI: installa, accedi e invia la tua prima email in due minuti.
CLI per agenti: il contratto agente completo: output JSON, codici di uscita, --dry-run, risposta di errore e discovery.
SDK: la stessa superficie API come librerie tipizzate per TypeScript, Go e Python.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Ottieni un brief di implementazione