Bird CLI

bird 是 Bird API 的命令行形态：一个二进制文件即可在 Bird 运行的所有渠道上发送消息、配置这些渠道，并管理它们所在的工作区。它同时为两类调用者而设计：终端前的人类用户，以及在循环中驱动它的 agent 或脚本。每条命令默认将 JSON 输出到 stdout，将错误以结构化错误响应写入 stderr，并以语义化退出码退出，消费方据此按结构分支，无需解析文本。

认证

代码示例

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 字段进行分支。传入 --offline 可跳过 API 调用，传入 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 打印将要发送的已解析请求体并直接退出，不执行发送：这是所有出站操作之前的验证关卡。
--idempotency-key <key> 使重试变得安全：服务器对任何具有相同 key 的重复请求都会重放原始响应，这与 SDK 使用的幂等机制相同，因此网络超时不会导致重复发送。

写命令还支持 --example，它会打印一个完整、有效的请求体（根据 API schema 生成，无需凭据）并退出。破坏性命令（delete）需要显式指定 ID 和 --yes，因此松散的重试不会悄悄地破坏状态。

输出契约

数据以 JSON 格式输出到 stdout，无需额外标志；诊断和错误输出到 stderr，绝不与数据混合。列表返回游标信封（{"data": [...], "next_cursor": ...}），默认 --limit，因此输出始终有界。通过管道传给 jq 提取字段（bird email list | jq -r '.data[].id'）。对于单记录读取（get、show、status），--format text（-f text）可切换为人类可读的卡片视图。

失败以 JSON 错误响应的形式输出到 stderr，包含可供机器分支的字段：code（稳定 ID）、type、retryable 和 retry_after、指向出错输入的 param 和 details，以及列出可运行恢复命令的 next（bird 命令）。API 错误会直接透传服务器的错误码、请求 ID 和文档链接。参阅错误了解底层 API 错误模型。

退出码是语义化的，脚本或 agent 无需读取任何文本即可分支：

退出码	含义
0	成功。
1	意外/未识别的错误。显示并停止。
2	无效的标志、参数或请求体。
3	资源未找到。
4	认证或授权失败。
5	冲突或前置条件失败。
6	请求速率限制或服务器错误，在 retry_after 后重试。
7	检查发现问题，例如 bird email templates check。

命令在输入缺失时以退出码 2 和可操作的提示报告，不会弹出交互式提示。bird auth login 会等待浏览器或设备批准。等待浏览器确认的命令会在 stderr 的 JSON 通知中打印审核链接和 confirmation_id。在命令等待完成期间，请保留该 ID 以便恢复。Create Call 预览功能使用的就是这个流程。确认完成后会返回记录的执行结果。如果确认过期、被取消或结束时没有该结果，命令以 5 退出。结果缺失并不能证明操作未执行。在创建新请求之前，请先核实其结果。如果中断，请使用 --confirmation-id <confirmation_id> 重复原始命令和幂等键以恢复。

配置

代码示例

bird config show

config show 打印已解析的配置：API 基础 URL 及其来源、配置/缓存/状态路径，以及生效的渠道默认值。基础 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 或 agent 沙箱。

两个全局标志适用于所有命令：

--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 对象。撰写（compose）只读取 reply_to、category、tags 和 metadata，因为它以邮箱身份发送。这些默认值与 SDK 在客户端构造时接受的相同，因此脚本和其 SDK 等价物可从相同地址发送。文件中无法识别的键会按名称拒绝，而非解析为永远不会生效的默认值。只有读取默认值的命令会因此失败；bird config show 会报告同样的错误，方便你找到拼写错误。

探索命令接口

代码示例

bird commands

此命令以 JSON 格式打印完整的命令树，包括每条命令的用途、标志、必需位置参数和错误契约。agent 可通过一次调用枚举整个接口，无需抓取 --help。使用 --example 或 --help 查看某条命令的详情，然后用 --dry-run 预览它。如需安全重试，使用 --idempotency-key 运行命令。Shell 补全通过 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 快速入门：安装、登录，两分钟内发送第一封邮件。
用于 agent 的 CLI：完整的 agent 契约：JSON 输出、退出码、--dry-run、错误响应和命令发现。
SDK：与 API 相同的接口，提供 TypeScript、Go 和 Python 的类型化库。

Bird CLI

安装

macOS 和 Linux

Windows

认证

初始命令

输出契约

配置

渠道默认值

探索命令接口

常用命令组

后续步骤

相关资源