Bird CLI

bird to Bird API w formie wiersza poleceń: jeden plik binarny, który wysyła na każdym kanale obsługiwanym przez Bird, konfiguruje te kanały i zarządza obszarem roboczym wokół nich. Jest zbudowany dla dwóch rodzajów wywołujących jednocześnie: człowieka przy terminalu oraz agenta lub skryptu sterującego nim w pętli. Każde polecenie domyślnie wysyła JSON na stdout, zapisuje błędy jako strukturalną odpowiedź na stderr i kończy się semantycznym kodem, dzięki czemu konsument rozgałęzia się na podstawie struktury, a nie parsowania tekstu.

Instalacja

macOS i Linux

Homebrew:

brew install messagebird/tap/bird

Lub skrypt instalacyjny:

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

Skrypt wykrywa platformę, weryfikuje pobrany plik i wypisuje, gdzie trafił plik binarny. Aby przypiąć wersję lub wybrać katalog docelowy, przekaż flagi przez potok za pomocą sh -s --:

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

Windows

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

Instaluje się do %LOCALAPPDATA%\bird\bin. Aby przypiąć wersję lub wybrać katalog, najpierw pobierz skrypt, ponieważ przesyłanie potokiem do iex nie pozwala przekazać parametrów:

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

Zweryfikuj instalację na dowolnej platformie poleceniem bird version.

Uwierzytelnianie

bird auth login --scope emails:write

To otwiera stronę zgody w przeglądarce, na której zatwierdzasz żądane uprawnienia do obszaru roboczego. Samo bird auth login żąda dostępu tylko do odczytu. Opcja --scope emails:write pozwala na powodzenie wysyłki e-maila w sekcji Pierwsze polecenia. Każde polecenie wymagające szerszego dostępu wypisuje dokładne polecenie ponownego logowania. CLI zapisuje token OAuth powiązany z obszarem roboczym w ~/.config/bird/credentials.json i automatycznie odświeża go przy użyciu. Nie musisz tworzyć ani kopiować klucza API, a zapisany region obszaru roboczego eliminuje konieczność konfigurowania hosta. Na maszynie bez interfejsu graficznego lub przez SSH bird auth login --device wypisuje kod, który zatwierdzasz na innym urządzeniu, zamiast otwierać lokalną przeglądarkę.

Sprawdź, czy dane uwierzytelniające działają:

bird auth status

auth status raportuje, czy token jest skonfigurowany i czy przechodzi walidację względem API, a także obszar roboczy, region i przyznane zakresy. Zawsze kończy się kodem 0, więc rozgałęziaj na podstawie pola valid w wyjściu JSON. Przekaż --offline, aby pominąć wywołanie API, i bird auth logout, aby usunąć zapisane dane uwierzytelniające.

Pierwsze polecenia

Wyślij e-mail i odczytaj go po ID:

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

Szybki start CLI przeprowadza przez ten przepływ od początku do końca, włącznie ze współdzieloną domeną onboardingową i adresem sandbox Bird, dzięki czemu możesz wysyłać, zanim zweryfikujesz własną domenę.

Mutacje przyjmują dane wejściowe na trzy sposoby, a wartość inline wygrywa: flagi, ciało JSON wskazane przez --body-file <path|-> (- czyta stdin) lub jedno i drugie, więc jeden zapisany szablon obsługuje wiele wywołań (bird email send --body-file body.json --to x@y.com). CLI nigdy nie czyta stdin, na który nie został skierowany. Dwie flagi sprawiają, że każdy zapis jest bezpieczny do próbnego uruchomienia i ponowienia:

• --dry-run wypisuje rozwiązane żądanie (jego method, url, nagłówek Idempotency-Key, jeśli ustawiony, i body) i kończy się bez wysyłania: bramka weryfikacyjna przed czymkolwiek wychodzącym.
• --idempotency-key <key> sprawia, że ponowienie jest bezpieczne: serwer odtwarza oryginalną odpowiedź dla każdego zduplikowanego żądania z tym samym kluczem, czyli ten sam mechanizm idempotentności, którego używają SDK-i, więc timeout sieciowy nigdy nie oznacza podwójnej wysyłki.

Komendy zapisu obsługują też --example, który wypisuje kompletne, poprawne ciało żądania (wygenerowane ze schematu API, bez potrzeby podawania poświadczeń) i kończy działanie. Komendy usuwające coś, takie jak delete i archive, wymagają jawnego ID oraz --yes, więc nieuważne ponowienie nie zadziała przypadkowo. Archiwizację możesz cofnąć odpowiednią komendą unarchive.

Kontrakt wyjściowy

Dane trafiają na stdout jako JSON bez potrzeby ustawiania flagi; diagnostyka i błędy trafiają na stderr, nigdy nie mieszając się z danymi. Listy zwracają kopertę kursorową ({"data": [...], "next_cursor": ...}) z domyślnym --limit, więc wyjście jest zawsze ograniczone. Przekieruj do jq, aby wyodrębnić pola (bird email list | jq -r '.data[].id'). Przy odczytach pojedynczego rekordu (get, show, status) --format text (-f text) przełącza na czytelną dla człowieka kartę.

Błędy to koperta JSON na stderr z polami umożliwiającymi maszynowe rozgałęzienie: code (stabilny identyfikator), type, retryable i retry_after, param i details dla błędnych danych wejściowych oraz next z listą wykonywalnych komend bird do odzyskania stanu. Błędy API przekazują wprost kod błędu serwera, ID żądania i link do dokumentacji. Każdy błąd zawiera czytelny message, a większość zawiera stabilny code. Błąd z Bird API zawiera również doc_url do strony tego kodu, która opisuje, co poszło nie tak i co zrobić. Wszystkie kody są wymienione w dokumentacji błędów. Zobacz Błędy, aby poznać bazowy model błędów API.

Kody zakończenia są semantyczne, więc skrypt lub agent rozgałęzia się bez czytania tekstu:

Polecenia zgłaszają brakujące dane wejściowe kodem zakończenia 2 i wskazówką do działania, bez interaktywnego monitu. bird auth login czeka na zatwierdzenie w przeglądarce lub na urządzeniu. Polecenia oczekujące na potwierdzenie w przeglądarce wypisują link do przeglądu i confirmation_id w komunikacie JSON na stderr. Zachowaj ID na potrzeby odzyskiwania, dopóki polecenie czeka na zakończenie. Funkcja Create Call w wersji zapoznawczej korzysta z tego przepływu. Zakończone potwierdzenie zwraca zarejestrowany wynik wykonania. Jeśli potwierdzenie wygaśnie, zostanie anulowane lub zakończy się bez tego wyniku, polecenie kończy działanie kodem 5. Brak wyniku nie dowodzi, że operacja nie została wykonana. Uzgodnij jej rezultat przed utworzeniem kolejnego żądania. W razie przerwania powtórz oryginalne polecenie i klucz idempotentności z --confirmation-id <confirmation_id>, aby wznowić.

Konfiguracja

bird config show

config show wypisuje rozwiązaną konfigurację: bazowy URL API i skąd pochodzi, ścieżki konfiguracji, pamięci podręcznej i stanu oraz wszelkie aktywne domyślne wartości kanałów. Bazowy URL jest rozwiązywany w kolejności: flaga globalna --base-url, zmienna środowiskowa BIRD_API_URL, a następnie region zapisany przy logowaniu ({region}.platform.bird.com). Po bird auth login rozwiązany region zwykle nie wymaga nadpisania. CLI stosuje ścieżki XDG (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); ustaw BIRD_CONFIG_DIR, aby zwinąć wszystkie trzy pod jeden katalog główny, co jest przydatne w izolowanych środowiskach CI lub sandboxach agentów.

Dwie flagi globalne działają w każdym poleceniu:

• --format (-f): json (domyślnie) lub text (tylko odczyty pojedynczego rekordu).
• --base-url: nadpisuje endpoint API dla jednego wywołania, odpowiednik BIRD_API_URL.

Domyślne wartości kanałów

Uruchom bird config show i użyj pliku zgłoszonego jako paths.config_file dla wartości, które inaczej powtarzałbyś przy każdej wysyłce. Ta ścieżka podąża za BIRD_CONFIG_DIR i lokalizacjami konfiguracji XDG. Skonfigurowana wartość domyślna wypełnia odpowiednie pole wysyłki, które pozostało nieustawione, a wartość przekazana w wywołaniu zawsze wygrywa:

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

Obiekt email przyjmuje from, reply_to, category, track_opens, track_clicks, headers, tags, metadata i ip_pool_id i stosuje się do bird email send, bird email send-batch i bird email mailboxes compose. Każda wartość jest zapisywana tak samo jak odpowiadająca jej flaga: adres to zwykły ciąg znaków lub ciąg Name <addr>, a headers i tags to obiekty name: value. Compose odczytuje tylko reply_to, category, tags i metadata, ponieważ wysyła jako skrzynka pocztowa. Są to te same wartości domyślne, które SDK-i przyjmują przy tworzeniu klienta, więc skrypt i jego odpowiednik SDK wysyłają z tego samego adresu. Klucz, którego plik nie rozpoznaje, jest odrzucany po nazwie, zamiast być parsowany do wartości domyślnej, która nigdy nie zadziała. Tylko polecenia odczytujące wartości domyślne zwracają błąd; bird config show zgłasza ten sam błąd, dzięki czemu możesz znaleźć literówkę.

Odkryj dostępne polecenia

bird commands

To wypisuje całe drzewo poleceń jako JSON, włącznie z przeznaczeniem każdego polecenia, flagami, wymaganymi argumentami pozycyjnymi i kontraktem błędów. Agent może wyliczyć całą powierzchnię jednym wywołaniem, zamiast skrobać --help. Użyj --example lub --help, aby zbadać polecenie, a następnie --dry-run, aby je podejrzeć. Aby bezpiecznie ponowić, uruchom polecenie z --idempotency-key. Autouzupełnianie w powłoce jest dostępne przez bird completion bash|zsh|fish.

Najczęściej używane grupy poleceń

Grupy, których użyjesz najpierw. CLI obejmuje znacznie więcej (SMS, WhatsApp, Verify, kontakty, odbiorców, rozliczenia, zgłoszenia do supportu i inne); uruchom bird commands, aby zobaczyć pełne drzewo.

• bird auth: login, status, logout: zarządzaj danymi uwierzytelniającymi OAuth.
• bird email: send, get, list: wysyłaj wiadomości i śledź status ich dostarczenia.
• bird email templates: create, get, list, update, delete, duplicate, preview: twórz szablony wielokrotnego użytku. versions submit zamraża szkic i czyni go wersją serwowaną przy wysyłce; versions languages set edytuje jego treść dla danego języka.
• bird email domains: create, get, list, verify: rejestruj domeny wysyłkowe i sprawdzaj weryfikację DNS.
• bird email inbound-addresses: create, get, list, update, delete: twórz adresy przekierowujące, na które Bird odbiera pocztę, i zarządzaj nimi.
• bird email inbound-messages: list, get, body, attachments: czytaj pocztę odebraną przez Bird.
• bird webhooks: create, get, list, test, delete: zarządzaj endpointami webhooków i uruchamiaj testowe dostarczenia.

Następne kroki

• Szybki start CLI: zainstaluj, zaloguj się i wyślij pierwszy e-mail w dwie minuty.
• CLI dla agentów: pełny kontrakt agenta: wyjście JSON, kody zakończenia, --dry-run, odpowiedź z błędem i odkrywanie poleceń.
• SDK-i: ta sama powierzchnia API jako typowane biblioteki dla TypeScript, Go i Python.