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 क्विकस्टार्ट इस पूरी प्रक्रिया को शुरू से अंत तक दिखाता है, जिसमें Bird का साझा ऑनबोर्डिंग डोमेन और सैंडबॉक्स पता भी शामिल है, ताकि आप अपना डोमेन सत्यापित करने से पहले ही भेज सकें।

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

--dry-run तैयार अनुरोध प्रिंट करता है (उसका method, url, सेट होने पर Idempotency-Key हेडर, और body) और भेजे बिना बाहर निकल जाता है। कुछ भी बाहर भेजने से पहले यही जाँच का चरण है।
--idempotency-key <key> फिर से प्रयास को सुरक्षित बनाता है: उसी कुंजी वाले किसी भी दोहराए गए अनुरोध के लिए सर्वर मूल प्रतिक्रिया ही लौटाता है। SDK भी यही आइडेम्पोटेंसी तरीका इस्तेमाल करते हैं, इसलिए नेटवर्क टाइमआउट होने पर संदेश दो बार नहीं जाता।

लेखन वाले कमांड --example भी सपोर्ट करते हैं, जो एक पूरी और मान्य अनुरोध बॉडी प्रिंट करके बाहर निकल जाता है। यह बॉडी API स्कीमा से बनती है और इसके लिए क्रेडेंशियल की ज़रूरत नहीं होती। कुछ हटाने वाले कमांड, जैसे delete और archive, के लिए स्पष्ट ID और --yes ज़रूरी हैं, ताकि कोई लापरवाह फिर से प्रयास गलती से कार्रवाई न कर दे। आर्काइव को आप संबंधित unarchive कमांड से वापस ले सकते हैं।

आउटपुट अनुबंध

डेटा बिना किसी फ़्लैग के JSON के रूप में stdout पर जाता है। डायग्नॉस्टिक्स और त्रुटियाँ stderr पर जाती हैं और डेटा के साथ कभी नहीं मिलतीं। सूचियाँ एक डिफ़ॉल्ट --limit के साथ कर्सर एनवेलप ({"data": [...], "next_cursor": ...}) लौटाती हैं, इसलिए आउटपुट हमेशा सीमित रहता है। फ़ील्ड निकालने के लिए आउटपुट को 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, और next, जो उबरने के लिए चलाए जा सकने वाले bird कमांड सूचीबद्ध करता है। API त्रुटियाँ सर्वर का त्रुटि कोड, अनुरोध ID और दस्तावेज़ लिंक सीधे आगे भेजती हैं। हर त्रुटि में पढ़ने योग्य message होता है, और ज़्यादातर में एक स्थिर code भी होता है। Bird API से आई त्रुटि में उस कोड के पेज का doc_url भी होता है, जो बताता है कि क्या गलत हुआ और क्या करना है। सभी कोड त्रुटि संदर्भ में सूचीबद्ध हैं। मूल 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 preview इसी प्रक्रिया का उपयोग करता है। पुष्टि पूरी होने पर दर्ज किया गया निष्पादन परिणाम लौटता है। अगर पुष्टि की समय-सीमा समाप्त हो जाए, वह रद्द हो जाए या उस परिणाम के बिना समाप्त हो जाए, तो कमांड 5 के साथ exit करता है। परिणाम न मिलने का अर्थ यह नहीं है कि ऑपरेशन नहीं चला। नया अनुरोध बनाने से पहले उसका नतीजा जाँच लें। अगर प्रक्रिया बाधित हो जाए, तो फिर से शुरू करने के लिए मूल कमांड और idempotency कुंजी को --confirmation-id <confirmation_id> के साथ दोहराएँ।

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

कोड उदाहरण

bird config show

config show लागू कॉन्फ़िगरेशन प्रिंट करता है: API base URL और उसका स्रोत, config, cache और state पाथ, और लागू कोई भी चैनल डिफ़ॉल्ट। base 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, संपर्क, ऑडियंस, बिलिंग, सपोर्ट टिकट और अन्य); पूरे ट्री के लिए 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 क्विकस्टार्ट: दो मिनट में इंस्टॉल करें, लॉग इन करें और अपना पहला ईमेल भेजें।
एजेंट के लिए CLI: पूरा एजेंट अनुबंध: JSON आउटपुट, एग्ज़िट कोड, --dry-run, त्रुटि प्रतिक्रिया और डिस्कवरी।
SDK: वही API सतह, TypeScript, Go और Python के लिए टाइप की गई लाइब्रेरी के रूप में।

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ

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