Sign inGet Started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

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:
Przykład kodu
brew install messagebird/tap/bird
Lub skrypt instalacyjny:
Przykład kodu
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 --:
Przykład kodu
curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version 1.2.3 --install-dir /opt/bird/bin

Windows

Przykład kodu
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:
Przykład kodu
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

Przykład kodu
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ą:
Przykład kodu
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:
Przykład kodu
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 ciało żądania, które zostałoby wysłane, 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.
Polecenia zapisu obsługują też --example, który wypisuje kompletne, poprawne ciało żądania (wygenerowane ze schematu API, bez potrzeby danych uwierzytelniających) i kończy działanie. Polecenia destrukcyjne (delete) wymagają jawnego ID i --yes, więc luźne ponowienie nie może po cichu zniszczyć stanu.

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 odpowiedź JSON na stderr z polami do maszynowego rozgałęziania: code (stabilny identyfikator), type, retryable i retry_after, param i details dla błędnego wejścia oraz next z listą uruchamialnych poleceń bird do naprawy. Błędy API przekazują kod błędu serwera, ID żądania i link do dokumentacji bez zmian. 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:
Kod zakończeniaZnaczenie
0Sukces.
1Nieoczekiwany / nierozpoznany błąd. Wyświetl i zatrzymaj.
2Nieprawidłowe flagi, argumenty lub ciało.
3Nie znaleziono zasobu.
4Błąd uwierzytelniania lub autoryzacji.
5Konflikt lub niespełniony warunek wstępny.
6Limit żądań lub błąd serwera, spróbuj ponownie po retry_after.
7Sprawdzenie wykryło problem, na przykład bird email templates check.
Komendy zgłaszają brakujące dane wejściowe kodem wyjścia 2 i wskazówką do działania, bez interaktywnego monitu. bird auth login czeka na zatwierdzenie w przeglądarce lub na urządzeniu. Komendy 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 komenda czeka na zakończenie. Funkcja Create Call w wersji zapoznawczej korzysta z tego mechanizmu. Zakończone potwierdzenie zwraca zarejestrowany wynik wykonania. Jeśli potwierdzenie wygaśnie, zostanie anulowane lub zakończy się bez tego wyniku, komenda kończy działanie z kodem 5. Brak wyniku nie dowodzi, że operacja nie została wykonana. Uzgodnij jej rezultat przed utworzeniem kolejnego żądania. W razie przerwania powtórz oryginalną komendę i klucz idempotentności z --confirmation-id <confirmation_id>, aby wznowić.

Konfiguracja

Przykład kodu
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:
Przykład kodu
{
  "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

Przykład kodu
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.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integrationPrzewodnik wdrożeniowySend your first email
Uzyskaj brief wdrożeniowy