# `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 browse its template catalogue       |

## Contacts & Audiences

| Name                                                           | Description               |
| -------------------------------------------------------------- | ------------------------- |
| [`contacts`](/docs/cli/reference/contacts)                     | Manage contacts           |
| [`audiences`](/docs/cli/reference/audiences)                   | Manage audiences          |
| [`contact-properties`](/docs/cli/reference/contact-properties) | Manage contact properties |

## Developer

| Name                                               | Description                            |
| -------------------------------------------------- | -------------------------------------- |
| [`webhooks`](/docs/cli/reference/webhooks)         | Manage outbound webhook endpoints      |
| [`verify`](/docs/cli/reference/verify)             | Send one-time passcodes and check them |
| [`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                                   |
| [`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)       | Manage the organization: members, invitations, and workspaces |
| [`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, text (default json) |