Sign inGet Started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

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:
Exemplo de código
brew install messagebird/tap/bird
Ou o script de instalação:
Exemplo de código
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 --:
Exemplo de código
curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version 1.2.3 --install-dir /opt/bird/bin

Windows

Exemplo de código
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:
Exemplo de código
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

Exemplo de código
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:
Exemplo de código
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:
Exemplo 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
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 o corpo da solicitação resolvido que seria enviado 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 esquema API, sem necessidade de credenciais) e encerra. Comandos destrutivos (delete) exigem um ID explícito e --yes, para que uma retentativa imprecisa não destrua estado silenciosamente.

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 que permitem decisão por máquina: code (ID estável), type, retryable e retry_after, param e details para a entrada com problema, e next listando comandos bird executáveis para recuperação. Erros API repassam o código de erro, o ID da solicitação e o link de documentação do servidor diretamente. Consulte Erros para o modelo de erro API subjacente.
Os códigos de saída são semânticos, de modo que um script ou agente decide sem ler nenhum texto:
Código de saídaSignificado
0Sucesso.
1Erro inesperado / não reconhecido. Exiba e pare.
2Flags, argumentos ou corpo inválidos.
3Recurso não encontrado.
4Falha de autenticação ou autorização.
5Conflito ou pré-condição falha.
6Limitação de requisições ou erro do servidor, tente novamente após retry_after.
7Uma verificação encontrou um problema, por exemplo bird email templates check.
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

Exemplo de código
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:
Exemplo de código
{
  "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

Exemplo de código
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.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Obtenha um resumo de implementação