Bird CLI

bird adalah Bird API dalam bentuk baris perintah: satu biner yang mengirim di setiap kanal yang dijalankan Bird, menyiapkan kanal-kanal tersebut, dan mengonfigurasi workspace di sekitarnya. Ia dibangun untuk dua pemanggil sekaligus: manusia di terminal, dan agen atau skrip yang menggerakkannya dalam loop. Setiap perintah mengeluarkan JSON ke stdout secara default, menulis kesalahan sebagai envelope terstruktur ke stderr, dan keluar dengan kode semantik, sehingga konsumen bercabang berdasarkan struktur, bukan mengurai teks.

Instalasi

macOS dan Linux

Homebrew:

Contoh kode

brew install messagebird/tap/bird

Atau skrip instalasi:

Contoh kode

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

Skrip ini mendeteksi platform Anda, memverifikasi unduhan, dan mencetak lokasi biner yang terpasang. Untuk mengunci rilis atau memilih tujuan, teruskan flag melalui pipe dengan sh -s --:

Contoh kode

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

Windows

Contoh kode

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

Biner terpasang ke %LOCALAPPDATA%\bird\bin. Untuk mengunci rilis atau memilih direktori, unduh skripnya terlebih dahulu, karena piping ke iex tidak menyediakan cara untuk meneruskan parameter:

Contoh kode

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

Verifikasi instalasi di platform mana pun dengan bird version.

Autentikasi

Contoh kode

bird auth login --scope emails:write

Perintah ini membuka halaman persetujuan di browser tempat Anda menyetujui izin workspace yang diminta. bird auth login tanpa opsi meminta akses baca-saja. Opsi --scope emails:write memungkinkan pengiriman email di Perintah pertama berhasil. Perintah apa pun yang membutuhkan akses lebih akan mencetak perintah login ulang yang tepat. CLI menyimpan token OAuth yang terikat workspace di ~/.config/bird/credentials.json dan memperbaruinya secara otomatis saat digunakan. Anda tidak perlu membuat atau menyalin kunci API, dan region workspace yang tercatat menghilangkan kebutuhan mengonfigurasi host. Di mesin tanpa layar atau melalui SSH, bird auth login --device mencetak kode yang Anda setujui di perangkat lain alih-alih membuka browser lokal.

Periksa apakah kredensial berfungsi:

Contoh kode

bird auth status

auth status melaporkan apakah token sudah dikonfigurasi dan apakah token tersebut valid terhadap API, beserta workspace, region, dan cakupan yang diberikan. Perintah ini selalu keluar dengan 0, jadi bercabanglah berdasarkan field valid di output JSON-nya. Gunakan --offline untuk melewati panggilan API, dan bird auth logout untuk membuang kredensial tersimpan.

Perintah pertama

Kirim email dan baca kembali berdasarkan ID:

Contoh kode

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

Quickstart CLI memandu alur ini dari awal hingga akhir, termasuk domain onboarding bersama dan alamat sandbox Bird, sehingga Anda bisa mengirim sebelum memverifikasi domain Anda sendiri.

Mutasi menerima input tiga cara, dan nilai inline yang menang: flag, body JSON yang ditunjuk oleh --body-file <path|-> (- membaca stdin), atau keduanya, sehingga satu template tersimpan melayani banyak panggilan (bird email send --body-file body.json --to x@y.com). CLI tidak pernah membaca stdin yang tidak ditunjuk kepadanya. Dua flag membuat setiap penulisan aman untuk diuji dan dicoba ulang:

--dry-run mencetak body permintaan yang sudah di-resolve yang akan dikirim, lalu keluar tanpa mengirim: gerbang verifikasi sebelum apa pun keluar.
--idempotency-key <key> membuat percobaan ulang aman: server memutar ulang respons asli untuk setiap permintaan duplikat dengan kunci yang sama, mekanisme idempotensi yang sama yang digunakan SDK, sehingga timeout jaringan tidak pernah berarti pengiriman ganda.

Perintah tulis juga mendukung --example, yang mencetak body permintaan lengkap dan valid (dihasilkan dari skema API, tanpa kredensial) lalu keluar. Perintah destruktif (delete) memerlukan ID eksplisit dan --yes, sehingga percobaan ulang yang longgar tidak bisa diam-diam menghancurkan state.

Kontrak output

Data dikirim ke stdout sebagai JSON tanpa perlu flag; diagnostik dan kesalahan dikirim ke stderr, tidak pernah tercampur dengan data. Daftar mengembalikan envelope kursor ({"data": [...], "next_cursor": ...}) dengan --limit default, sehingga output selalu terbatas. Pipe ke jq untuk mengekstrak field (bird email list | jq -r '.data[].id'). Pada pembacaan rekaman tunggal (get, show, status), --format text (-f text) beralih ke kartu yang mudah dibaca manusia.

Kegagalan adalah envelope JSON di stderr dengan field yang bisa dibaca mesin: code (ID stabil), type, retryable dan retry_after, param dan details untuk input yang bermasalah, dan next yang mencantumkan perintah bird yang bisa dijalankan untuk pemulihan. Kesalahan API meneruskan kode kesalahan server, ID permintaan, dan tautan dokumentasi apa adanya. Lihat Errors untuk model kesalahan API yang mendasarinya.

Kode keluar bersifat semantik, sehingga skrip atau agen bercabang tanpa membaca teks apa pun:

Kode keluar	Arti
0	Berhasil.
1	Kesalahan tidak terduga / tidak dikenali. Tampilkan dan hentikan.
2	Flag, argumen, atau body tidak valid.
3	Resource tidak ditemukan.
4	Kegagalan autentikasi atau otorisasi.
5	Konflik atau prasyarat gagal.
6	Pembatasan laju permintaan atau kesalahan server, coba lagi setelah retry_after.
7	Pemeriksaan menemukan masalah, misalnya bird email templates check.

Perintah melaporkan input yang kurang dengan exit 2 beserta petunjuk yang dapat ditindaklanjuti, tanpa prompt interaktif. bird auth login menunggu persetujuan dari browser atau perangkat. Perintah yang menunggu konfirmasi browser mencetak tautan peninjauan dan confirmation_id dalam pemberitahuan JSON di stderr. Simpan ID tersebut untuk pemulihan selagi perintah menunggu penyelesaian. Pratinjau Create Call menggunakan alur ini. Konfirmasi yang selesai mengembalikan hasil eksekusi yang tercatat. Jika konfirmasi kedaluwarsa, dibatalkan, atau berakhir tanpa hasil tersebut, perintah keluar dengan 5. Tidak adanya hasil tidak membuktikan bahwa operasi tidak berjalan. Rekonsiliasi hasilnya sebelum membuat permintaan baru. Jika terputus, ulangi perintah asli dan kunci idempotensi dengan --confirmation-id <confirmation_id> untuk melanjutkan.

Konfigurasi

Contoh kode

bird config show

config show mencetak konfigurasi yang sudah di-resolve: URL dasar API dan asalnya, path config, cache, dan state, serta default kanal yang berlaku. URL dasar di-resolve secara berurutan: flag global --base-url, variabel environment BIRD_API_URL, lalu region yang tercatat saat login Anda ({region}.platform.bird.com). Setelah bird auth login, region yang di-resolve biasanya tidak perlu di-override. CLI mengikuti path XDG (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); atur BIRD_CONFIG_DIR untuk menyatukan ketiganya di bawah satu root, berguna untuk sandbox CI atau agen yang terisolasi.

Dua flag global berlaku di setiap perintah:

--format (-f): json (default) atau text (hanya pembacaan rekaman tunggal).
--base-url: override endpoint API untuk satu pemanggilan, setara dengan BIRD_API_URL.

Default kanal

Jalankan bird config show dan gunakan file yang dilaporkan sebagai paths.config_file untuk nilai yang biasanya Anda ulangi di setiap pengiriman. Path ini mengikuti BIRD_CONFIG_DIR dan lokasi konfigurasi XDG. Default yang dikonfigurasi mengisi field yang cocok pada pengiriman yang membiarkannya kosong, dan nilai yang diteruskan ke panggilan selalu menang:

Contoh kode

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

Objek email menerima from, reply_to, category, track_opens, track_clicks, headers, tags, metadata, dan ip_pool_id, dan berlaku untuk bird email send, bird email send-batch, dan bird email mailboxes compose. Setiap nilai ditulis sesuai cara flag yang cocok ditulis: alamat berupa string biasa atau Name <addr>, dan headers serta tags adalah objek name: value. Compose hanya membaca reply_to, category, tags, dan metadata, karena compose mengirim sebagai mailbox. Ini adalah default yang sama yang diterima SDK pada konstruksi klien, sehingga skrip dan padanan SDK-nya mengirim dari alamat yang sama. Kunci yang tidak dikenali file ditolak berdasarkan nama, bukan diurai menjadi default yang tidak pernah berlaku. Hanya perintah yang membaca default yang gagal karenanya; bird config show melaporkan kesalahan yang sama, sehingga Anda bisa menemukan typo-nya.

Jelajahi surface

Contoh kode

bird commands

Perintah ini mencetak seluruh pohon perintah sebagai JSON, termasuk tujuan, flag, positional wajib, dan kontrak kesalahan setiap perintah. Agen dapat mengenumerasi seluruh surface dalam satu panggilan alih-alih scraping --help. Gunakan --example atau --help untuk memeriksa sebuah perintah, lalu --dry-run untuk mempratinjaunya. Untuk percobaan ulang yang aman, jalankan perintah dengan --idempotency-key. Penyelesaian shell tersedia melalui bird completion bash|zsh|fish.

Grup perintah umum

Grup yang akan Anda gunakan pertama kali. CLI mencakup lebih banyak (SMS, WhatsApp, Verify, kontak, audiens, billing, tiket dukungan, dan lainnya); jalankan bird commands untuk pohon lengkapnya.

bird auth: login, status, logout: kelola kredensial OAuth.
bird email: send, get, list: kirim pesan dan lacak status pengirimannya.
bird email templates: create, get, list, update, delete, duplicate, preview: buat template yang dapat digunakan ulang. versions submit membekukan draf dan menjadikannya versi yang dilayani pengiriman; versions languages set mengedit konten per bahasanya.
bird email domains: create, get, list, verify: daftarkan domain pengiriman dan periksa verifikasi DNS.
bird email inbound-addresses: create, get, list, update, delete: buat dan kelola alamat penerusan tempat Bird menerima email.
bird email inbound-messages: list, get, body, attachments: baca email yang diterima Bird.
bird webhooks: create, get, list, test, delete: kelola endpoint webhook dan jalankan pengiriman uji.

Langkah selanjutnya

Quickstart CLI: instal, login, dan kirim email pertama Anda dalam dua menit.
CLI untuk agen: kontrak agen lengkap: output JSON, kode keluar, --dry-run, respons kesalahan, dan discovery.
SDK: surface API yang sama sebagai pustaka bertipe untuk TypeScript, Go, dan Python.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Dapatkan ringkasan implementasi