# `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 and read its senders                                        |
| [`voice`](/docs/cli/reference/voice)       | Read the call log and statistics, manage what admits a call, and place a test call |
| [`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                                  |

## Contacts & Audiences

| Name                                                           | Description                                                 |
| -------------------------------------------------------------- | ----------------------------------------------------------- |
| [`contacts`](/docs/cli/reference/contacts)                     | Manage contacts, identified by email, phone, or external ID |
| [`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      |

## 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)                           |