bird-cli skill

Bird CLI

bird is a single binary for the Bird API and local tools such as WhatsApp message previews. Account operations need credentials; local previews do not.

This skill requires the bird CLI. If command -v bird finds nothing, install it by following the CLI installation instructions.

Each references/ link below points to a file beside this one. If your copy has no references/ folder, read the same path from the Bird MCP server as skill://bird-cli/references/<file>, or from https://raw.githubusercontent.com/messagebird/bird-ai/main/plugins/bird/skills/bird-cli/references/<file>.

The path

Step 0 — Authenticate for account operations. For a WhatsApp preview, go directly to Preview; for public documentation questions, use docs. For account operations, confirm credentials first: authenticate. It is a no-op when bird auth status already reports valid: true. No account yet? Create one through onboarding; it ends by storing the same credential a login would.

Step 1 — Run the operation the user asked for:

• Send or inspect email messages (bird email, including send-batch) → email
• Author reusable email templates, submit a draft, or roll one back (bird email templates) → email-templates
• Prepare, send, or inspect a marketing broadcast (bird email broadcasts) → email-broadcasts
• Send or inspect SMS messages, or browse SMS templates (bird sms) → sms
• Draft the carrier verification a US toll-free number needs before it can send, read what the carrier asks for, or see why one was declined (bird sms tfn verifications) → tfn-verifications
• Claim an alphanumeric SMS sender, find out what a country requires of it, or register it for a country (bird sms senders) → sms-senders
• Group an SMS program's senders, reply numbers and sending defaults under one profile a send can name, or create, change and delete such a profile (bird sms messaging-profiles) → sms-messaging-profiles
• Reply to Apple Messages conversations, reuse attachments by ID, or manage businesses and statistics (bird amb) → Apple Messages
• Preview a WhatsApp message (bird whatsapp preview) → Preview (local — skips Step 0)
• Send or inspect WhatsApp messages, receipts, reactions, senders, suppressions, keyword rules or statistics (bird whatsapp) → WhatsApp operations
• Connect a number the workspace holds to WhatsApp (bird whatsapp numbers create) or repair a failed one when its next carries a repairWhatsAppNumber step (bird whatsapp numbers repair), or find the dashboard guide for one held with another provider, one in the WhatsApp Business app, or one on personal WhatsApp → Connecting a number
• Browse WhatsApp templates, their versions, and each version's per-language content (bird whatsapp templates) → whatsapp-templates
• Draft, edit, check, test, send, cancel or follow a WhatsApp broadcast to an audience (bird whatsapp broadcasts) → whatsapp-broadcasts
• Create and administer WhatsApp groups, hand out or rotate an invite link, decide join requests, pin messages, or remove a participant (bird whatsapp groups) → whatsapp-groups
• Triage the WhatsApp inbox — list conversations, read a thread, assign, label, resolve or mark one read (bird whatsapp conversations) → whatsapp-conversations
• Set up the WhatsApp Business Agent on a number — onboard it, give it FAQs, websites, files and skills, test it, then turn it on (bird whatsapp agents) → whatsapp-agents
• Inspect voice calls, find out why one was refused, configure a SIP trunk or an inbound number, manage ring groups for the browser phone, register or verify an outbound caller ID, enable or disable calling to a country, or place a test call (bird voice) → voice
• Buy an eSIM, add data, deliver installation details, or manage recurring packages (bird esim) → eSIM
• Provision Realtime apps and rotate the keys their clients connect with (bird realtime) → realtime
• Verify a recipient with a one-time passcode — send a code, then check what they submit (bird verify verifications) → verify
• Find out about a recipient before you use it — grade an email address, or identify a phone number and its network (bird lookup) → lookup
• Manage media-library assets and folders (bird assets) → media library
• Manage contacts, audiences, and contact properties (bird contacts, bird audiences, bird contact-properties) → contacts
• Record and look up messaging consent grants and opt-outs (bird preferences) → preferences
• Manage sending domains (bird email domains), or find a verified from to send from → domains
• Count how much mail the workspace received, by period, day or hour (bird email stats inbound) → received-mail-stats
• Inspect owned-domain placement and authentication, or configure, register and read seed tests (bird email inbox-insights) → inbox-insights
• Inspect competitive email intelligence (bird email competitive) → competitive
• Style the hosted page a marketing recipient lands on when they unsubscribe (bird email unsubscribe-page) → unsubscribe-page
• Manage dedicated IPs (bird email dedicated-ips), IP pools (bird email ip-pools) and which workspaces use them (sending reputation) → ip-pools
• Receive email at inbound forward addresses (bird email inbound-addresses), or read the mail received there (bird email inbound-messages) → inbound
• Manage outbound webhook endpoints, deliver to a platform such as a Claude agent through a connector, or send events to Zapier, Make, n8n or your own endpoint and prove one arrives → webhooks
• Require client certificates on API requests, or present a client certificate on webhook deliveries (bird workspace mtls, bird webhooks client-certificate) → mtls
• Rotate the signing secret of SMS callback URLs and voice sequence webhooks, see whether callbacks reached the receiver, or replay the failed ones (bird webhooks callbacks) → webhooks-callbacks
• Issue or rotate a workspace API key (bird api-keys create, bird api-keys rotate) → api-keys (needs a login carrying api_keys:write; an API key cannot run it)
• With several workspaces, or a workspace limit or enabled allocation left after a deletion: diagnose workspace request rates → read limits; set a workspace limit → set a workspace limit; remove it → clear a workspace limit
• Find out why acquiring a number, registering a sender, or registering or resubmitting a 10DLC brand was refused for a reason about the organization rather than the country, and settle the requirement behind it (bird trust) → trust
• Find the business a 10DLC brand is registered for, so brands create can name it (bird compliance identities list) → compliance-identities
• Download a registration's blank form (bird compliance document-templates get) → download a form
• Upload evidence for a registration (bird compliance attachments upload) → upload a document
• Inspect an uploaded document (bird compliance attachments get) → inspect a document
• Delete an unused upload (bird compliance attachments delete) → delete a document
• Register a 10DLC brand for US A2P traffic, or file a submission against one (bird sms 10dlc brands create, bird sms 10dlc brands submissions create) → sibling operations; node not yet authored, --help on each carries the field list
• Open a support ticket, reply to it, or wait for a support agent reply → support
• Send the person's suggestions or rough edges to the Bird team (bird platform feedback); when something is broken and blocking, open a support ticket instead (bird platform support create) → feedback (needs an OAuth login; an API key cannot run it)
• Check whether Bird itself has an incident or maintenance before debugging the person's setup (bird platform status) → service status (public, skips Step 0)
• Find a review link you lost, or check which requests are still waiting for browser confirmation before proposing one again (bird operation-confirmations list) → operation confirmations (needs an OAuth login; an API key cannot run it)
• Read one proposal by id, its status and its recorded result (bird operation-confirmations get) → read a proposal (needs an OAuth login; an API key cannot run it)
• Answer a how-to or reference question about Bird from the documentation → docs (public — skips Step 0)
• Read workspace resource limits (bird workspace quotas list, bird organization workspaces quotas list) → read resource quotas
• Set or change an organization-managed workspace ceiling (bird organization workspaces quotas update) → set a resource ceiling
• Remove an organization-managed workspace ceiling (bird organization workspaces quotas delete) → clear a resource ceiling
• Keep several workspaces signed in, pick one per command, or switch the default (bird auth login --profile, bird profile list, bird profile set) → profiles
• Inspect resolved CLI configuration → bird config show (sibling operation; node not yet authored)

Pick the operation that matches the request. Complete Step 0 only for operations that require an account.

Conventions every command shares

These hold across operations, so the nodes rely on them instead of repeating them:

• Output is JSON by default (--format json). Single-record commands (get, status, show) also take --format text for a human-readable card. List commands ignore --format text and always emit JSON, so a script can pipe them through jq without a per-command branch.
• Exit codes carry the failure category so a caller can branch without parsing prose: 2 invalid usage or input, 3 not found, 4 auth or permission denied, 5 conflict, 6 transient (rate limit or server error, retry after retry_after), 7 a check ran and found a problem (check_failed), 1 anything else. Errors print to stderr; data to stdout.
• Every error explains itself. The envelope always carries a readable message, and most errors carry a stable code. An error from the Bird API also carries a doc_url to that code's page, which says what went wrong and what to do; every code is listed at https://bird.com/docs/api/errors. Read details, when present, for each failing field.
• Transient failures are retried for you. A rate limit, a 5xx, or a network blip is retried twice with backoff before the command fails, so an error marked retryable has already been through that — re-running it immediately rarely helps. --max-retries 0 turns it off when you drive your own retry loop.
• Retry progress goes to stderr. The CLI reports the retry reason and remaining wait there; JSON result data stays on stdout.
• The login sets the region. The token from bird auth login is bound to one workspace and its region, which picks the API host; override with --base-url/BIRD_API_URL. Details and the state check live in authenticate.