Bird CLI

bird एक कमांड लाइन के रूप में Bird API है: एक बाइनरी जो Bird द्वारा संचालित हर चैनल पर भेजती है, उन चैनलों को सेटअप करती है, और उनके आसपास वर्कस्पेस को कॉन्फ़िगर करती है। यह एक साथ दो कॉलर्स के लिए बनी है: टर्मिनल पर एक व्यक्ति, और लूप में इसे चलाने वाला एजेंट या स्क्रिप्ट। हर कमांड डिफ़ॉल्ट रूप से stdout पर JSON देता है, stderr पर एक स्ट्रक्चर्ड एन्वेलप के रूप में त्रुटियाँ लिखता है, और एक सिमैंटिक कोड के साथ एग्ज़िट करता है, ताकि कंज़्यूमर प्रोज़ पार्स करने के बजाय स्ट्रक्चर पर ब्रांच कर सके।

इंस्टॉल करें

macOS और Linux

Homebrew:

कोड उदाहरण

brew install messagebird/tap/bird

या इंस्टॉल स्क्रिप्ट:

कोड उदाहरण

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

स्क्रिप्ट आपके प्लेटफ़ॉर्म का पता लगाती है, डाउनलोड को वेरिफ़ाई करती है, और बताती है कि बाइनरी कहाँ रखी गई। किसी रिलीज़ को पिन करने या डेस्टिनेशन चुनने के लिए, 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

यह %LOCALAPPDATA%\bird\bin में इंस्टॉल होता है। किसी रिलीज़ को पिन करने या डायरेक्टरी चुनने के लिए, पहले स्क्रिप्ट डाउनलोड करें, क्योंकि iex में पाइप करने पर पैरामीटर पास करने का कोई तरीका नहीं बचता:

कोड उदाहरण

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

किसी भी प्लेटफ़ॉर्म पर bird version से इंस्टॉल वेरिफ़ाई करें।

प्रमाणित करें

कोड उदाहरण

bird auth login --scope emails:write

यह एक ब्राउज़र सहमति पेज खोलता है जहाँ आप अनुरोधित वर्कस्पेस अनुमतियों को स्वीकृत करते हैं। केवल bird auth login रीड-ओनली एक्सेस का अनुरोध करता है। --scope emails:write विकल्प पहले कमांड में ईमेल भेजने को सफल बनाता है। जिस कमांड को अधिक एक्सेस चाहिए, वह सटीक री-लॉगिन कमांड प्रिंट करता है। CLI एक वर्कस्पेस-बाउंड OAuth टोकन ~/.config/bird/credentials.json में स्टोर करता है और उपयोग पर इसे स्वचालित रूप से रिफ़्रेश करता है। आपको API की बनाने या कॉपी करने की ज़रूरत नहीं है, और रिकॉर्ड किया गया वर्कस्पेस रीजन होस्ट कॉन्फ़िगर करने की आवश्यकता हटा देता है। हेडलेस मशीन या SSH पर, bird auth login --device लोकल ब्राउज़र खोलने के बजाय एक कोड प्रिंट करता है जिसे आप दूसरे डिवाइस पर स्वीकृत करते हैं।

जाँचें कि क्रेडेंशियल काम कर रहा है:

कोड उदाहरण

bird auth status

auth status बताता है कि टोकन कॉन्फ़िगर है या नहीं और यह API के विरुद्ध वैलिडेट होता है या नहीं, साथ ही वर्कस्पेस, रीजन, और दी गई स्कोप। यह हमेशा 0 से एग्ज़िट करता है, इसलिए इसके JSON आउटपुट में valid फ़ील्ड पर ब्रांच करें। API कॉल छोड़ने के लिए --offline पास करें, और स्टोर किए गए क्रेडेंशियल को हटाने के लिए bird auth logout पास करें।

पहले कमांड

एक ईमेल भेजें और उसे 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

CLI quickstart इस फ़्लो को शुरू से अंत तक दिखाता है, जिसमें Bird का शेयर्ड ऑनबोर्डिंग डोमेन और सैंडबॉक्स एड्रेस शामिल है, ताकि आप अपना डोमेन वेरिफ़ाई करने से पहले भेज सकें।

म्यूटेशन तीन तरीकों से इनपुट लेते हैं, और इनलाइन वैल्यू जीतती है: फ़्लैग, --body-file <path|-> द्वारा नामित JSON बॉडी (- stdin पढ़ता है), या दोनों, ताकि एक स्टोर किया हुआ टेम्पलेट कई कॉल के काम आए (bird email send --body-file body.json --to x@y.com)। CLI कभी भी वह stdin नहीं पढ़ता जिसकी ओर उसे पॉइंट नहीं किया गया। दो फ़्लैग हर राइट को रिहर्स और फिर से प्रयास करने के लिए सुरक्षित बनाते हैं:

--dry-run रिज़ॉल्व्ड रिक्वेस्ट बॉडी प्रिंट करता है जो भेजी जाती और बिना भेजे एग्ज़िट करता है: किसी भी आउटबाउंड चीज़ से पहले सत्यापन गेट।
--idempotency-key <key> फिर से प्रयास को सुरक्षित बनाता है: सर्वर समान की वाले किसी भी डुप्लिकेट रिक्वेस्ट के लिए मूल रिस्पॉन्स रीप्ले करता है, वही आइडेम्पोटेंसी मैकेनिज़्म जो SDKs उपयोग करते हैं, ताकि नेटवर्क टाइमआउट का मतलब कभी डबल सेंड न हो।

राइट कमांड --example को भी सपोर्ट करते हैं, जो एक पूर्ण, वैलिड रिक्वेस्ट बॉडी प्रिंट करता है (API स्कीमा से जनरेट, बिना क्रेडेंशियल के) और एग्ज़िट करता है। डिस्ट्रक्टिव कमांड (delete) को एक स्पष्ट ID और --yes की ज़रूरत होती है, ताकि कोई लूज़ रिट्राई चुपचाप स्टेट नष्ट न कर सके।

आउटपुट कॉन्ट्रैक्ट

डेटा बिना किसी फ़्लैग के JSON के रूप में stdout पर जाता है; डायग्नोस्टिक्स और त्रुटियाँ stderr पर जाती हैं, डेटा के साथ कभी मिक्स नहीं होतीं। लिस्ट एक कर्सर एन्वेलप ({"data": [...], "next_cursor": ...}) डिफ़ॉल्ट --limit के साथ लौटाती हैं, ताकि आउटपुट हमेशा बाउंडेड रहे। फ़ील्ड निकालने के लिए jq में पाइप करें (bird email list | jq -r '.data[].id')। सिंगल-रिकॉर्ड रीड (get, show, status) पर, --format text (-f text) इसके बजाय ह्यूमन-रीडेबल कार्ड चुनता है।

विफलताएँ stderr पर एक JSON एन्वेलप होती हैं जिसमें मशीन-ब्रांचेबल फ़ील्ड होती हैं: code (स्थिर ID), type, retryable और retry_after, गलत इनपुट के लिए param और details, और रिकवर करने के लिए चलाने योग्य bird कमांड की next सूची। API त्रुटियाँ सर्वर का एरर कोड, रिक्वेस्ट ID, और डॉक्स लिंक सीधे पास करती हैं। अंतर्निहित API एरर मॉडल के लिए त्रुटियाँ देखें।

एग्ज़िट कोड सिमैंटिक हैं, इसलिए स्क्रिप्ट या एजेंट बिना कोई टेक्स्ट पढ़े ब्रांच करता है:

एग्ज़िट कोड	अर्थ
0	सफलता।
1	अप्रत्याशित / अपरिचित त्रुटि। दिखाएँ और रुकें।
2	अमान्य फ़्लैग, आर्ग्युमेंट, या बॉडी।
3	रिसोर्स नहीं मिला।
4	प्रमाणीकरण या प्राधिकरण विफलता।
5	कॉन्फ़्लिक्ट या विफल प्रीकंडिशन।
6	दर सीमा या सर्वर त्रुटि, retry_after के बाद फिर से प्रयास करें।
7	एक जाँच में समस्या मिली, उदाहरण के लिए bird email templates check।

कमांड्स गायब इनपुट को exit 2 और एक कार्रवाई योग्य संकेत के साथ रिपोर्ट करती हैं, बिना किसी इंटरैक्टिव प्रॉम्प्ट के। bird auth login ब्राउज़र या डिवाइस अनुमोदन की प्रतीक्षा करता है। ब्राउज़र पुष्टि की प्रतीक्षा करने वाली कमांड्स stderr पर JSON नोटिस में एक रिव्यू लिंक और confirmation_id प्रिंट करती हैं। कमांड के पूरा होने की प्रतीक्षा के दौरान रिकवरी के लिए ID को बनाए रखें। Create Call का प्रीव्यू संस्करण इसी फ़्लो का उपयोग करता है। पूर्ण हुई पुष्टि रिकॉर्ड किया गया निष्पादन परिणाम लौटाती है। यदि पुष्टि की समय-सीमा समाप्त हो जाती है, रद्द कर दी जाती है, या उस परिणाम के बिना समाप्त होती है, तो कमांड 5 से बाहर निकलती है। गायब परिणाम यह साबित नहीं करता कि ऑपरेशन नहीं चला। एक और अनुरोध बनाने से पहले उसके परिणाम का मिलान करें। यदि बाधित हो जाए, तो फिर से शुरू करने के लिए मूल कमांड और idempotency key को --confirmation-id <confirmation_id> के साथ दोहराएँ।

कॉन्फ़िगरेशन

कोड उदाहरण

bird config show

config show रिज़ॉल्व्ड कॉन्फ़िगरेशन प्रिंट करता है: API बेस URL और वह कहाँ से आया, config, cache, और state पाथ, और कोई भी प्रभावी चैनल डिफ़ॉल्ट। बेस URL इस क्रम में रिज़ॉल्व होता है: --base-url ग्लोबल फ़्लैग, BIRD_API_URL एनवायरनमेंट वेरिएबल, फिर आपके लॉगिन के साथ रिकॉर्ड किया गया रीजन ({region}.platform.bird.com)। bird auth login के बाद, रिज़ॉल्व्ड रीजन को आमतौर पर ओवरराइड की ज़रूरत नहीं होती। CLI XDG पाथ (~/.config/bird, ~/.cache/bird, ~/.local/state/bird) का पालन करता है; तीनों को एक रूट में समेटने के लिए BIRD_CONFIG_DIR सेट करें, जो आइसोलेटेड CI या एजेंट सैंडबॉक्स के लिए उपयोगी है।

दो ग्लोबल फ़्लैग हर कमांड पर काम करते हैं:

--format (-f): json (डिफ़ॉल्ट) या text (केवल सिंगल-रिकॉर्ड रीड)।
--base-url: एक इन्वोकेशन के लिए API एंडपॉइंट ओवरराइड करें, BIRD_API_URL के बराबर।

चैनल डिफ़ॉल्ट

bird config show चलाएँ और paths.config_file के रूप में रिपोर्ट की गई फ़ाइल का उपयोग उन वैल्यू के लिए करें जो आप अन्यथा हर सेंड पर दोहराते। यह पाथ BIRD_CONFIG_DIR और XDG कॉन्फ़िगरेशन लोकेशन का पालन करता है। कॉन्फ़िगर किया गया डिफ़ॉल्ट उस सेंड के मैचिंग फ़ील्ड को भरता है जो उसे अनसेट छोड़ता है, और कॉल को पास की गई वैल्यू हमेशा जीतती है:

कोड उदाहरण

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

email ऑब्जेक्ट from, reply_to, category, track_opens, track_clicks, headers, tags, metadata, और ip_pool_id लेता है, और bird email send, bird email send-batch, और bird email mailboxes compose पर लागू होता है। हर वैल्यू उसी तरह लिखी जाती है जैसे मैचिंग फ़्लैग: एड्रेस एक प्लेन या Name <addr> स्ट्रिंग है, और headers और tags name: value ऑब्जेक्ट हैं। कंपोज़ केवल reply_to, category, tags, और metadata पढ़ता है, क्योंकि यह मेलबॉक्स के रूप में भेजता है। ये वही डिफ़ॉल्ट हैं जो SDK क्लाइंट कंस्ट्रक्शन पर स्वीकार करते हैं, ताकि स्क्रिप्ट और उसका SDK समकक्ष एक ही एड्रेस से भेजें। जिस की को फ़ाइल पहचान नहीं पाती, उसे नाम से अस्वीकार किया जाता है, न कि किसी ऐसे डिफ़ॉल्ट में पार्स किया जाता है जो कभी लागू नहीं होता। केवल वे कमांड जो डिफ़ॉल्ट पढ़ते हैं, इस पर विफल होते हैं; bird config show इसके बजाय वही त्रुटि रिपोर्ट करता है, ताकि आप टाइपो ढूँढ सकें।

सरफ़ेस खोजें

कोड उदाहरण

bird commands

यह पूरे कमांड ट्री को JSON के रूप में प्रिंट करता है, जिसमें हर कमांड का उद्देश्य, फ़्लैग, आवश्यक पोज़िशनल, और एरर कॉन्ट्रैक्ट शामिल है। एजेंट --help स्क्रैप करने के बजाय एक कॉल में पूरा सरफ़ेस एन्यूमरेट कर सकता है। कमांड इंस्पेक्ट करने के लिए --example या --help का उपयोग करें, फिर प्रीव्यू के लिए --dry-run। सुरक्षित फिर से प्रयास के लिए, कमांड को --idempotency-key के साथ चलाएँ। शेल कम्प्लीशन bird completion bash|zsh|fish के ज़रिए उपलब्ध है।

सामान्य कमांड ग्रुप

वे ग्रुप जो आप पहले उपयोग करेंगे। CLI में और भी बहुत कुछ है (SMS, WhatsApp, Verify, contacts, audiences, billing, support tickets, और अन्य); पूरे ट्री के लिए bird commands चलाएँ।

bird auth: login, status, logout: OAuth क्रेडेंशियल प्रबंधित करें।
bird email: send, get, list: संदेश भेजें और उनकी डिलीवरी स्थिति ट्रैक करें।
bird email templates: create, get, list, update, delete, duplicate, preview: पुन: उपयोग योग्य टेम्पलेट बनाएँ। versions submit ड्राफ़्ट को फ़्रीज़ करता है और उसे वह वर्शन बनाता है जो सेंड सर्व करते हैं; versions languages set उसकी प्रति-भाषा सामग्री संपादित करता है।
bird email domains: create, get, list, verify: सेंडिंग डोमेन रजिस्टर करें और DNS सत्यापन जाँचें।
bird email inbound-addresses: create, get, list, update, delete: फ़ॉरवर्डिंग एड्रेस बनाएँ और प्रबंधित करें जिन पर Bird मेल प्राप्त करता है।
bird email inbound-messages: list, get, body, attachments: Bird द्वारा प्राप्त मेल पढ़ें।
bird webhooks: create, get, list, test, delete: webhook एंडपॉइंट प्रबंधित करें और टेस्ट डिलीवरी फ़ायर करें।

अगले कदम

CLI quickstart: इंस्टॉल करें, लॉग इन करें, और दो मिनट में अपना पहला ईमेल भेजें।
एजेंट के लिए CLI: पूर्ण एजेंट कॉन्ट्रैक्ट: JSON आउटपुट, एग्ज़िट कोड, --dry-run, त्रुटि प्रतिक्रिया एन्वेलप, और डिस्कवरी।
SDKs: TypeScript, Go, और Python के लिए टाइप्ड लाइब्रेरी के रूप में वही API सरफ़ेस।

संबंधित संसाधन