Download the PHP package heitoralthmann/conta-azul-cli without Composer

Conta Azul CLI

English: unofficial PHP CLI wrapping the Conta Azul API (Financeiro, Pessoas, Produtos, Serviços, Contratos, Notas Fiscais, Vendas, Orçamentos, Captura) for consumption by AI agents. The Conta Azul API is Brazil-only, so the rest of this documentation is in Portuguese.

CLI em PHP/Symfony que expõe as famílias Financeiro (Finanças, Baixas, Cobranças), Pessoas, Produtos, Serviços, Contratos, Notas Fiscais, Vendas, Orçamentos e Captura da API Conta Azul para consumo por agentes de IA.

Cada invocação é de curta duração: faz uma chamada, escreve TOON em stdout e sai. Toda a complexidade de OAuth2 — fluxo inicial, persistência, refresh, rotação de token — fica encapsulada dentro do CLI.

O consumidor primário é um agente, não um humano. Por isso a saída padrão é TOON (mais compacto em tokens que JSON), o exit code é binário e os erros vêm em envelope estruturado com um campo kind estável. JSON compacto continua disponível com --format=json.

Projeto não oficial. Este CLI não é mantido, endossado ou afiliado à Conta Azul. É um cliente de terceiros para a API pública da Conta Azul.

📚 Documentação

A documentação completa está em docs/ — e é publicada como site em https://heitoralthmann.github.io/conta-azul-cli/.

Para agentes, a mesma documentação sai em forma de dados: llms.txt e llms-full.txt.

Requisitos

• PHP 8.4.1+ com as extensões mbstring, openssl e ctype (esta última já vem habilitada na maioria das builds)
• posix é opcional e só existe em Unix; toda chamada a ela é guardada, e o CLI roda sem ela — é assim que a suíte passa em windows-latest no CI
• Composer — só para o clone e para construir o PHAR; o PHAR pronto roda com PHP e mais nada
• Uma aplicação registrada no portal de desenvolvedores da Conta Azul (client_id + client_secret)
• Uma conta Conta Azul com plano elegível para uso da API

Instalação

Três canais. O Homebrew é o caminho de uso em macOS e Linux; o PHAR é o mesmo binário sem Homebrew por perto (e o caminho do Windows); o clone é o caminho de desenvolvimento.

Homebrew — resolve o PHP 8.4.1+ como dependência e dá brew upgrade:

O brew trust é exigido pelo Homebrew 6 para fórmulas de taps não oficiais — a receita confia na fórmula, não no tap inteiro. Instala o mesmo .phar da release, sob dois nomes: ca e conta-azul-cli. Se você já tem outro ca no PATH — inclusive de uma instalação manual anterior — o brew install avisa que o nome está sombreado.

Binário único (PHAR) — um ca global, sem repositório por perto:

~/.local/bin precisa estar no PATH. Para construir o mesmo artefato a partir do fonte, composer build:phar — e composer smoke:phar para conferi-lo antes de instalar.

O .sha256 prova que o download não corrompeu. Para provar também que o binário saiu deste repositório, o workflow de release atesta a proveniência do que publica:

O que ela garante — e o que não garante — está em Proveniência.

No Windows o PHAR é invocado por php conta-azul-cli.phar (ou por um ca.cmd de uma linha), o checksum se confere com Get-FileHash, e o build local precisa de WSL ou Git Bash. A receita está em Instalação.

Clone + Composer — para mexer no código:

Composer — para quem já vive no ecossistema PHP:

O pacote está no Packagist como heitoralthmann/conta-azul-cli. Vale a ressalva de que composer global usa um espaço de dependências compartilhado com as suas outras ferramentas globais; o PHAR e o Homebrew não têm esse problema.

Configuração

Numa instalação global, os comandos ca config funcionam sem credencial nenhuma — são justamente o caminho para criá-la:

Num clone, cp .env.example .env continua funcionando.

O .env e o tokens.json nascem 0600, em diretório 0700 — em Unix. No Windows o PHP não escreve bits de permissão, e a proteção desses dois arquivos fica por conta das ACLs do perfil do usuário: a seção "Permissões dos arquivos" de Configuração explica o que a garantia cobre e o que não cobre.

O arquivo de ambiente é procurado nesta ordem, e o primeiro que existir vence, sem mesclagem: CA_CLI_ENV_FILE → <raiz do repo>/.env → ~/.config/conta-azul-cli/.env. ca config path responde qual está valendo e por quê. A precedência geral é: flag de CLI → variável de ambiente → arquivo → default compilado. Em produção, use variáveis de ambiente. .env e tokens.json nunca devem ser versionados.

O provedor da Conta Azul recusa redirect_uri em http://localhost: exige HTTPS e um domínio real. O default compilado já é https://conta-azul-cli.ddev.site:9876/callback, e ca auth login emite o certificado TLS em ~/.config/conta-azul-cli/certs/ — sem checkout e sem mkcert. A receita completa — incluindo por que o domínio precisa ser *.ddev.site e por que CA_AUTHORIZE_URL e CA_TOKEN_URL andam em par — está em Configuração.

Autenticação

O refresh é automático e invisível. Para CI, veja ambientes headless.

Uso

Taxonomia: ca <substantivo> <verbo> [args].

Sucesso: documento TOON em stdout, stderr vazio, exit code 0. Erro: um envelope estruturado em stderr, stdout vazio, exit code 1.

O exit code é binário por design: o agente despacha sobre kind, não sobre o número. O enum de kind é contrato estável.

Desenvolvimento

Layout

A referência de comandos é gerada

docs/referencia/, docs/commands.json e docs/llms*.txt saem de composer docs:generate, que lê as definições do Symfony Console e mescla os fragmentos curados de docs/_data/commands/. O CI roda composer docs:check, que falha quando uma nota cita um comando ou parâmetro que não existe mais, quando um comando existente não está documentado, ou quando um grupo novo não aparece no nav do mkdocs.yml.

Veja o site localmente com pip install -r docs/requirements.txt && mkdocs serve.

Idioma

Superfície humana em pt-BR: README, --help, descrições, campo message do envelope. Superfície de máquina em inglês e estável: valores de kind, nomes de campo do envelope, variáveis de ambiente, identificadores e mensagens de commit.

Limitações conhecidas

• docs/financial-apis-openapi.yaml ainda é um placeholder: a Conta Azul não publica uma URL estável para a spec OpenAPI, então não há automação de detecção de mudança na API — acompanhamento é manual (veja CONTRIBUTING.md).

Contribuição e segurança

Quer contribuir? Veja SECURITY.md — não abra uma issue pública.

Licença

Apache 2.0. Veja LICENSE.