# `bird`

## Usage

```bash
bird
```

## Description

Authenticate, configure, and operate the Bird API from the command line.

Output is JSON by default; pass --format text for a human-readable card on
single-record reads (get, show). Errors and diagnostics go to stderr, never
mixed with data on stdout.

Mutations (send, create, test) take input from flags, a JSON body via
--body-file ("-" reads stdin), or both — a flag overrides the matching body
field. Run a command with --example to print its body shape, --dry-run to
preview the request without sending, and --idempotency-key to make a retry
safe.

Run "bird commands" to print the whole command tree as JSON.

## Channels

| Name                                       | Description                                                               |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| [`email`](/docs/cli/reference/email)       | Send and receive email and manage its deliverability resources            |
| [`sms`](/docs/cli/reference/sms)           | Send SMS and manage its messaging resources                               |
| [`whatsapp`](/docs/cli/reference/whatsapp) | Send WhatsApp messages, connect its senders, and read templates and stats |
| [`voice`](/docs/cli/reference/voice)       | Place and read calls, read legs and statistics, and configure Voice       |
| [`amb`](/docs/cli/reference/amb)           | Reply to Apple Messages for Business conversations                        |
| [`realtime`](/docs/cli/reference/realtime) | Provision Realtime apps and the keys their clients connect with           |
| [`numbers`](/docs/cli/reference/numbers)   | Search, buy and release the numbers you send from                         |
| [`esim`](/docs/cli/reference/esim)         | Register interest in Bird eSIM before it is generally available           |

## Contacts & Audiences

| Name                                                           | Description                                                 |
| -------------------------------------------------------------- | ----------------------------------------------------------- |
| [`contacts`](/docs/cli/reference/contacts)                     | Manage contacts, identified by email, phone, or external ID |
| [`preferences`](/docs/cli/reference/preferences)               | Record and look up messaging consent grants and opt-outs    |
| [`audiences`](/docs/cli/reference/audiences)                   | Group contacts into named audiences to send to              |
| [`contact-properties`](/docs/cli/reference/contact-properties) | Define the custom fields a contact can carry                |

## Developer

| Name                                               | Description                                  |
| -------------------------------------------------- | -------------------------------------------- |
| [`webhooks`](/docs/cli/reference/webhooks)         | Manage outbound webhook endpoints            |
| [`verify`](/docs/cli/reference/verify)             | Send one-time passcodes and check them       |
| [`lookup`](/docs/cli/reference/lookup)             | Find out about a recipient before you use it |
| [`docs`](/docs/cli/reference/docs)                 | Search the Bird documentation                |
| [`request-logs`](/docs/cli/reference/request-logs) | Inspect your API request logs                |

## Account

| Name                                                     | Description                                                        |
| -------------------------------------------------------- | ------------------------------------------------------------------ |
| [`auth`](/docs/cli/reference/auth)                       | Manage Bird API credentials                                        |
| [`api-keys`](/docs/cli/reference/api-keys)               | Issue API keys for the workspace                                   |
| [`billing`](/docs/cli/reference/billing)                 | Inspect billing plans and pricing                                  |
| [`support-tickets`](/docs/cli/reference/support-tickets) | Open and follow up on Bird support tickets                         |
| [`members`](/docs/cli/reference/members)                 | Manage workspace members                                           |
| [`invitations`](/docs/cli/reference/invitations)         | Manage workspace invitations                                       |
| [`organization`](/docs/cli/reference/organization)       | Administer the organization a credential belongs to                |
| [`workspace`](/docs/cli/reference/workspace)             | Inspect the current workspace and its settings                     |
| [`compliance`](/docs/cli/reference/compliance)           | What a registration must supply before a country approves it       |
| [`trust`](/docs/cli/reference/trust)                     | The requirements your organization must satisfy before it can send |

## CLI

| Name                                       | Description                               |
| ------------------------------------------ | ----------------------------------------- |
| [`config`](/docs/cli/reference/config)     | Inspect CLI configuration                 |
| [`version`](/docs/cli/reference/version)   | Print the CLI version                     |
| [`update`](/docs/cli/reference/update)     | Update the bird CLI to the latest release |
| [`commands`](/docs/cli/reference/commands) | Print the full command tree as JSON       |
| [`mcp`](/docs/cli/reference/mcp)           | Serve Bird as MCP tools over stdio        |
| [`whoami`](/docs/cli/reference/whoami)     | Show the signed-in user (id, email, name) |

## Examples

```bash
# Sign in (opens a browser)
bird auth login

# Send an email from a JSON body
bird email send --body-file message.json

# List recent messages and pull their ids
bird email list | jq -r '.data[].id'
```

## Options

| Name                | Description                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--base-url`        | API base URL (or set BIRD\_API\_URL)                                                                            |
| `--format, -f`      | Output format: json, or text where offered (single-record commands; collections are always JSON) (default json) |
| `--max-retries <n>` | Retries after a transient failure, 0 to disable (or set BIRD\_MAX\_RETRIES) (default 2)                         |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)