Sign inGet Started
Comenzar
Guías
Referencia de API
SDKs
CLI
Base de conocimientos
Registro de cambios

Bird CLI

bird es la Bird API en forma de línea de comandos: un solo binario que envía por cada canal que Bird gestiona, configura esos canales y ajusta el espacio de trabajo que los rodea. Está pensado para dos consumidores a la vez: una persona en una terminal y un agente o script que lo ejecuta en bucle. Cada comando emite JSON a stdout de forma predeterminada, escribe errores como una respuesta estructurada en stderr y sale con un código semántico, de modo que el consumidor ramifica según la estructura en lugar de analizar texto.

Instalación

macOS y Linux

Homebrew:
Ejemplo de código
brew install messagebird/tap/bird
O el script de instalación:
Ejemplo de código
curl -fsSL https://cli.bird.com/install.sh | sh
El script detecta tu plataforma, verifica la descarga e indica dónde quedó el binario. Para fijar una versión o elegir el destino, pasa los flags a través del pipe con sh -s --:
Ejemplo de código
curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version 1.2.3 --install-dir /opt/bird/bin

Windows

Ejemplo de código
irm https://cli.bird.com/install.ps1 | iex
Se instala en %LOCALAPPDATA%\bird\bin. Para fijar una versión o elegir un directorio, descarga el script primero, porque enviar por pipe a iex no permite pasar parámetros:
Ejemplo de código
irm https://cli.bird.com/install.ps1 -OutFile install.ps1
.\install.ps1 -Version 1.2.3 -InstallDir C:\tools\bird
Verifica la instalación en cualquier plataforma con bird version.

Autenticación

Ejemplo de código
bird auth login --scope emails:write
Esto abre una página de consentimiento en el navegador donde apruebas los permisos solicitados del espacio de trabajo. Un bird auth login sin más solicita acceso de solo lectura. La opción --scope emails:write permite que el envío de correo en Primeros comandos funcione. Cualquier comando que necesite más acceso imprime el comando exacto para volver a iniciar sesión. CLI almacena un token OAuth vinculado al espacio de trabajo en ~/.config/bird/credentials.json y lo refresca automáticamente en cada uso. No necesitas crear ni copiar una clave API, y la región del espacio de trabajo registrada elimina la necesidad de configurar un host. En una máquina sin pantalla o por SSH, bird auth login --device imprime un código que apruebas en otro dispositivo en lugar de abrir un navegador local.
Comprueba que la credencial funciona:
Ejemplo de código
bird auth status
auth status informa si hay un token configurado y si se valida contra API, además del espacio de trabajo, la región y los scopes concedidos. Siempre sale con 0, así que ramifica según el campo valid en su salida JSON. Pasa --offline para omitir la llamada a API, y bird auth logout para descartar la credencial almacenada.

Primeros comandos

Envía un correo y consúltalo por ID:
Ejemplo de código
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
El quickstart de CLI recorre este flujo de principio a fin, incluyendo el dominio compartido de onboarding y la dirección sandbox de Bird, para que puedas enviar antes de verificar un dominio propio.
Las mutaciones aceptan entrada de tres formas, y el valor inline gana: flags, un cuerpo JSON indicado por --body-file <path|-> (- lee stdin), o ambos, de modo que una plantilla almacenada sirve para muchas llamadas (bird email send --body-file body.json --to x@y.com). CLI nunca lee stdin si no se le indicó. Dos flags hacen que cada escritura sea segura de ensayar y reintentar:
  • --dry-run imprime el cuerpo de solicitud resuelto que se enviaría y sale sin enviarlo: la puerta de verificación antes de cualquier salida.
  • --idempotency-key <key> hace que un reintento sea seguro: el servidor reproduce la respuesta original para cualquier solicitud duplicada con la misma clave, el mismo mecanismo de idempotencia que usan los SDKs, de modo que un timeout de red nunca significa un envío doble.
Los comandos de escritura también admiten --example, que imprime un cuerpo de solicitud completo y válido (generado a partir del esquema API, sin necesidad de credenciales) y sale. Los comandos destructivos (delete) requieren un ID explícito y --yes, para que un reintento suelto no destruya estado silenciosamente.

Contrato de salida

Los datos van a stdout como JSON sin necesidad de ningún flag; los diagnósticos y errores van a stderr, nunca mezclados con los datos. Las listas devuelven una respuesta con cursor ({"data": [...], "next_cursor": ...}) con un --limit predeterminado, de modo que la salida siempre está acotada. Redirige a jq para extraer campos (bird email list | jq -r '.data[].id'). En lecturas de un solo registro (get, show, status), --format text (-f text) opta por una tarjeta legible en su lugar.
Los fallos son una respuesta JSON en stderr con campos ramificables por máquina: code (ID estable), type, retryable y retry_after, param y details para la entrada infractora, y next con comandos bird ejecutables para recuperarse. Los errores API pasan directamente el código de error del servidor, el ID de solicitud y el enlace a la documentación. Consulta Errores para el modelo de error API subyacente.
Los códigos de salida son semánticos, de modo que un script o agente ramifica sin leer texto:
Código de salidaSignificado
0Éxito.
1Error inesperado o no reconocido. Muéstralo y detente.
2Flags, argumentos o cuerpo no válidos.
3Recurso no encontrado.
4Fallo de autenticación o autorización.
5Conflicto o precondición fallida.
6Limitación de solicitudes o error del servidor, reintenta después de retry_after.
7Una comprobación encontró un problema, por ejemplo bird email templates check.
Los comandos informan de la entrada faltante con el código de salida 2 y una indicación accionable, sin solicitud interactiva. bird auth login espera la aprobación en el navegador o en el dispositivo. Los comandos que esperan confirmación en el navegador imprimen un enlace de revisión y confirmation_id en un aviso JSON en stderr. Conserva el ID para recuperación mientras el comando espera a completarse. La vista previa de Create Call usa este mecanismo. Una confirmación completada devuelve el resultado de ejecución registrado. Si la confirmación expira, se cancela o termina sin ese resultado, el comando sale con 5. Que falte el resultado no demuestra que la operación no se ejecutó. Reconcilia su resultado antes de crear otra solicitud. Si se interrumpe, repite el comando original y la clave de idempotencia con --confirmation-id <confirmation_id> para reanudar.

Configuración

Ejemplo de código
bird config show
config show imprime la configuración resuelta: la URL base de API y de dónde proviene, las rutas de config, caché y estado, y cualquier valor predeterminado de canal vigente. La URL base se resuelve en este orden: el flag global --base-url, la variable de entorno BIRD_API_URL, luego la región registrada con tu inicio de sesión ({region}.platform.bird.com). Después de bird auth login, la región resuelta normalmente no necesita sobreescritura. CLI sigue las rutas XDG (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); establece BIRD_CONFIG_DIR para colapsar las tres bajo una sola raíz, útil para sandboxes aislados de CI o agentes.
Dos flags globales funcionan en todos los comandos:
  • --format (-f): json (predeterminado) o text (solo lecturas de un registro).
  • --base-url: sobreescribe el endpoint API para una invocación, equivalente a BIRD_API_URL.

Valores predeterminados de canal

Ejecuta bird config show y usa el archivo indicado como paths.config_file para los valores que de otro modo repetirías en cada envío. Esta ruta sigue BIRD_CONFIG_DIR y las ubicaciones de configuración XDG. Un valor predeterminado configurado rellena el campo correspondiente de un envío que lo deje vacío, y un valor pasado en la llamada siempre gana:
Ejemplo de código
{
  "email": {
    "from": "hello@acme.com",
    "reply_to": ["support@acme.com"],
    "tags": { "team": "growth" },
    "ip_pool_id": "ipp_01krdgeqcxet5s7t44vh8rt9mg"
  }
}
El objeto email acepta from, reply_to, category, track_opens, track_clicks, headers, tags, metadata y ip_pool_id, y se aplica a bird email send, bird email send-batch y bird email mailboxes compose. Cada valor se escribe como su flag correspondiente: una dirección es una cadena simple o Name <addr>, y headers y tags son objetos name: value. Un compose lee solo reply_to, category, tags y metadata, porque envía como el buzón. Son los mismos valores predeterminados que los SDKs aceptan en la construcción del cliente, de modo que un script y su equivalente SDK envían desde la misma dirección. Una clave que el archivo no reconoce se rechaza por nombre en lugar de convertirse en un valor predeterminado que nunca se aplica. Solo los comandos que leen valores predeterminados fallan con ella; bird config show reporta el mismo error, para que puedas encontrar la errata.

Descubre la superficie

Ejemplo de código
bird commands
Esto imprime el árbol completo de comandos como JSON, incluyendo el propósito de cada comando, sus flags, posicionales requeridos y contrato de errores. Un agente puede enumerar toda la superficie en una sola llamada en lugar de rastrear --help. Usa --example o --help para inspeccionar un comando, luego --dry-run para previsualizarlo. Para reintentos seguros, ejecuta el comando con --idempotency-key. El autocompletado de shell está disponible mediante bird completion bash|zsh|fish.

Grupos de comandos comunes

Los grupos que usarás primero. CLI cubre mucho más (SMS, WhatsApp, Verify, contactos, audiencias, facturación, tickets de soporte y otros); ejecuta bird commands para ver el árbol completo.
  • bird auth: login, status, logout: gestiona la credencial OAuth.
  • bird email: send, get, list: envía mensajes y rastrea su estado de entrega.
  • bird email templates: create, get, list, update, delete, duplicate, preview: crea plantillas reutilizables. versions submit congela un borrador y lo convierte en la versión que sirven los envíos; versions languages set edita su contenido por idioma.
  • bird email domains: create, get, list, verify: registra dominios de envío y comprueba la verificación DNS.
  • bird email inbound-addresses: create, get, list, update, delete: crea y gestiona las direcciones de reenvío en las que Bird recibe correo.
  • bird email inbound-messages: list, get, body, attachments: lee el correo que Bird recibió.
  • bird webhooks: create, get, list, test, delete: gestiona endpoints de webhook y dispara entregas de prueba.

Próximos pasos

  • Quickstart de CLI: instala, inicia sesión y envía tu primer correo en dos minutos.
  • CLI para agentes: el contrato completo para agentes: salida JSON, códigos de salida, --dry-run, respuesta de error y descubrimiento.
  • SDKs: la misma superficie API como bibliotecas tipadas para TypeScript, Go y Python.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Obtener un resumen de implementación