Bird CLI

bird é a Bird API como linha de comando: um único binário que envia por todos os canais que Bird opera, configura esses canais e ajusta o espaço de trabalho ao redor deles. Ele é feito para dois tipos de chamador ao mesmo tempo: uma pessoa em um terminal e um agente ou script executando-o em loop. Todo comando emite JSON em stdout por padrão, grava erros como uma resposta de erro estruturada em stderr e encerra com um código semântico, de modo que o consumidor decide com base na estrutura em vez de interpretar texto.

Instalação

macOS e Linux

Homebrew:

brew install messagebird/tap/bird

Ou o script de instalação:

curl -fsSL https://cli.bird.com/install.sh | sh

O script detecta sua plataforma, verifica o download e informa onde o binário foi instalado. Para fixar uma versão ou escolher o destino, passe as flags pelo pipe com sh -s --:

curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version 1.2.3 --install-dir /opt/bird/bin

Windows

irm https://cli.bird.com/install.ps1 | iex

Ele instala em %LOCALAPPDATA%\bird\bin. Para fixar uma versão ou escolher um diretório, baixe o script primeiro, porque o pipe para iex não permite passar parâmetros:

irm https://cli.bird.com/install.ps1 -OutFile install.ps1
.\install.ps1 -Version 1.2.3 -InstallDir C:\tools\bird

Verifique a instalação em qualquer plataforma com bird version.

Autenticação

bird auth login --scope emails:write

Isso abre uma página de consentimento no navegador onde você aprova as permissões solicitadas para o espaço de trabalho. Um bird auth login simples solicita acesso somente leitura. A opção --scope emails:write permite que o envio de e-mail em Primeiros comandos funcione. Qualquer comando que precise de mais acesso imprime o comando exato de re-login. O CLI armazena um token OAuth vinculado ao espaço de trabalho em ~/.config/bird/credentials.json e o atualiza automaticamente a cada uso. Você não precisa criar nem copiar uma chave API, e a região do espaço de trabalho registrada elimina a necessidade de configurar um host. Em uma máquina headless ou via SSH, bird auth login --device imprime um código que você aprova em outro dispositivo em vez de abrir um navegador local.

Verifique se a credencial funciona:

bird auth status

auth status informa se um token está configurado e se ele é válido no API, além do espaço de trabalho, região e escopos concedidos. Ele sempre encerra com 0, então use o campo valid na saída JSON para decidir. Passe --offline para pular a chamada API e bird auth logout para descartar a credencial armazenada.

Primeiros comandos

Envie um e-mail e leia-o de volta pelo 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

O quickstart do CLI percorre esse fluxo de ponta a ponta, incluindo o domínio de onboarding compartilhado e o endereço sandbox do Bird, para que você possa enviar antes de verificar um domínio próprio.

Mutações aceitam entrada de três formas, e o valor inline tem prioridade: flags, um corpo JSON indicado por --body-file <path|-> (- lê stdin), ou ambos, de modo que um template armazenado serve várias chamadas (bird email send --body-file body.json --to x@y.com). O CLI nunca lê stdin para o qual não foi direcionado. Duas flags tornam toda escrita segura para ensaiar e tentar novamente:

• --dry-run imprime a solicitação resolvida (seu method, url, o header Idempotency-Key quando definido e o body) e encerra sem enviar: a porta de verificação antes de qualquer saída.
• --idempotency-key <key> torna uma retentativa segura: o servidor reproduz a resposta original para qualquer solicitação duplicada com a mesma chave, o mesmo mecanismo de idempotência que os SDKs usam, de modo que um timeout de rede nunca significa um envio duplicado.

Comandos de escrita também suportam --example, que imprime um corpo de solicitação completo e válido (gerado a partir do schema API, sem necessidade de credenciais) e encerra. Comandos que removem algo, como delete e archive, exigem um ID explícito e --yes, para que uma nova tentativa acidental não execute a ação. Você pode desfazer um arquivamento com o comando unarchive correspondente.

Contrato de saída

Dados vão para stdout como JSON sem precisar de flag; diagnósticos e erros vão para stderr, nunca misturados com dados. Listas retornam uma resposta com cursor ({"data": [...], "next_cursor": ...}) com um --limit padrão, de modo que a saída é sempre limitada. Use pipe para jq para extrair campos (bird email list | jq -r '.data[].id'). Em leituras de registro único (get, show, status), --format text (-f text) opta por um cartão legível por humanos.

Falhas são uma resposta de erro JSON em stderr com campos processáveis por máquina: code (ID estável), type, retryable e retry_after, param e details para a entrada problemática, e next listando comandos bird executáveis para recuperação. Erros API repassam diretamente o código de erro do servidor, o ID da solicitação e o link da documentação. Todo erro traz um message legível, e a maioria traz um code estável. Um erro da Bird API também traz um doc_url para a página daquele código, que explica o que deu errado e o que fazer. Todos os códigos estão listados na referência de erros. Consulte Erros para o modelo de erros API subjacente.

Os códigos de saída são semânticos, de modo que um script ou agente decide sem ler nenhum texto:

Comandos reportam entrada ausente com exit 2 e uma dica acionável, sem prompt interativo. bird auth login aguarda a aprovação no navegador ou dispositivo. Comandos que aguardam confirmação no navegador exibem um link de revisão e confirmation_id em um aviso JSON no stderr. Guarde o ID para recuperação enquanto o comando aguarda a conclusão. A prévia de Create Call usa esse fluxo. Uma confirmação concluída retorna o resultado de execução registrado. Se a confirmação expirar, for cancelada ou terminar sem esse resultado, o comando sai com 5. A ausência de resultado não prova que a operação não foi executada. Reconcilie o resultado antes de criar outra solicitação. Se houver interrupção, repita o comando original e a chave de idempotência com --confirmation-id <confirmation_id> para retomar.

Configuração

bird config show

config show imprime a configuração resolvida: a URL base do API e de onde ela veio, os caminhos de config, cache e estado, e quaisquer padrões de canal em vigor. A URL base é resolvida nesta ordem: a flag global --base-url, a variável de ambiente BIRD_API_URL e então a região registrada no seu login ({region}.platform.bird.com). Após bird auth login, a região resolvida normalmente não precisa de substituição. O CLI segue os caminhos XDG (~/.config/bird, ~/.cache/bird, ~/.local/state/bird); defina BIRD_CONFIG_DIR para consolidar os três sob uma única raiz, útil para sandboxes isolados de CI ou agente.

Duas flags globais funcionam em todos os comandos:

• --format (-f): json (padrão) ou text (somente leituras de registro único).
• --base-url: substitui o endpoint API para uma invocação, equivalente a BIRD_API_URL.

Padrões de canal

Execute bird config show e use o arquivo reportado como paths.config_file para valores que você repetiria em cada envio. Esse caminho segue BIRD_CONFIG_DIR e os locais de configuração XDG. Um padrão configurado preenche o campo correspondente de um envio que o deixa vazio, e um valor passado na chamada sempre tem prioridade:

{
  "email": {
    "from": "hello@acme.com",
    "reply_to": ["support@acme.com"],
    "tags": { "team": "growth" },
    "ip_pool_id": "ipp_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

O objeto email aceita from, reply_to, category, track_opens, track_clicks, headers, tags, metadata e ip_pool_id, e se aplica a bird email send, bird email send-batch e bird email mailboxes compose. Cada valor é escrito da mesma forma que a flag correspondente: um endereço é uma string simples ou Name <addr>, e headers e tags são objetos name: value. Um compose lê apenas reply_to, category, tags e metadata, porque envia como a mailbox. Esses são os mesmos padrões que os SDKs aceitam na construção do client, de modo que um script e seu equivalente SDK enviam do mesmo endereço. Uma chave que o arquivo não reconhece é recusada pelo nome em vez de ser interpretada como um padrão que nunca se aplica. Apenas os comandos que leem padrões falham nela; bird config show reporta o mesmo erro, para que você encontre o erro de digitação.

Descubra a superfície

bird commands

Isso imprime a árvore completa de comandos como JSON, incluindo o propósito de cada comando, flags, posicionais obrigatórios e contrato de erro. Um agente pode enumerar toda a superfície em uma chamada em vez de fazer scraping de --help. Use --example ou --help para inspecionar um comando, e --dry-run para pré-visualizá-lo. Para retentativas seguras, execute o comando com --idempotency-key. Autocompletar no shell está disponível via bird completion bash|zsh|fish.

Grupos de comando comuns

Os grupos que você usará primeiro. O CLI cobre muito mais (SMS, WhatsApp, Verify, contatos, audiências, cobrança, tickets de suporte e outros); execute bird commands para a árvore completa.

• bird auth: login, status, logout: gerencie a credencial OAuth.
• bird email: send, get, list: envie mensagens e acompanhe o status de entrega.
• bird email templates: create, get, list, update, delete, duplicate, preview: crie templates reutilizáveis. versions submit congela um rascunho e o torna a versão que os envios servem; versions languages set edita o conteúdo por idioma.
• bird email domains: create, get, list, verify: registre domínios de envio e verifique a verificação DNS.
• bird email inbound-addresses: create, get, list, update, delete: crie e gerencie os endereços de encaminhamento nos quais Bird recebe e-mails.
• bird email inbound-messages: list, get, body, attachments: leia os e-mails que Bird recebeu.
• bird webhooks: create, get, list, test, delete: gerencie endpoints de webhook e dispare entregas de teste.

Próximos passos

• Quickstart do CLI: instale, faça login e envie seu primeiro e-mail em dois minutos.
• O CLI para agentes: o contrato completo para agentes: saída JSON, códigos de saída, --dry-run, resposta de erro e descoberta.
• SDKs: a mesma superfície API como bibliotecas tipadas para TypeScript, Go e Python.