{
  "markdown": "# Kobana CLI\n\nCLI para a API da [Kobana](https://kobana.com.br) — acesso completo às APIs v1 e v2 direto do terminal.\n\nProjetado para humanos e agentes de IA, com saída JSON estruturada, introspecção de schema, dry-run e paginação automática.\n\n```\nkobana <servico> <recurso> <metodo> [flags]\n```\n\n![Kobana CLI Demo](docs/demo.gif)\n\n## Instalação\n\n### Homebrew (macOS e Linux)\n\n```bash\nbrew tap universokobana/tap\nbrew install kobana\n```\n\nPara atualizar:\n\n```bash\nbrew update && brew upgrade kobana\n```\n\n### Binários pré-compilados\n\nBaixe o binário para sua plataforma na [página de Releases](https://github.com/universokobana/kobana-cli/releases/latest) e coloque no seu `PATH`.\n\n### Nix\n\n```bash\n# Rodar direto do GitHub\nnix run github:universokobana/kobana-cli\n\n# Instalar no perfil\nnix profile install github:universokobana/kobana-cli\n```\n\n### Build a partir do source\n\n```bash\ngit clone https://github.com/universokobana/kobana-cli.git\ncd kobana-cli\ncargo install --path crates/kobana-cli\n```\n\nRequer [Rust](https://rustup.rs/) 1.70+.\n\n## Autenticação\n\n### Token de acesso (mais simples)\n\nObtenha o token em *Integracões > API > Token de API* na interface da Kobana.\n\n```bash\nexport KOBANA_TOKEN=seu_token_aqui\n```\n\n### OAuth (PKCE)\n\nO CLI usa OAuth com PKCE — funciona sem configurar nada:\n\n```bash\n# Login (abre browser, zero config)\nkobana auth login\n\n# Login com escopos específicos (default: read)\nkobana auth login --scopes \"read,write\"\n\n# Client credentials (para apps server-side)\nkobana auth login --client-id <ID> --client-secret <SECRET>\n\n# Ver status\nkobana auth status\n\n# Exportar credenciais (para CI)\nkobana auth export > credentials.json\n\n# Logout\nkobana auth logout\n```\n\nCredenciais salvas são criptografadas com AES-256-GCM. A chave fica no keyring do OS (macOS Keychain, etc.) com fallback para arquivo.\n\n### Prioridade de resolução\n\n| Prioridade | Método | Configuração |\n|------------|--------|--------------|\n| 1 | Token direto | `KOBANA_TOKEN` |\n| 2 | Arquivo de credenciais | `KOBANA_CREDENTIALS_FILE` |\n| 3 | Credenciais salvas | `kobana auth login` |\n\n### Ambientes\n\nO CLI opera em três ambientes. **Produção é o default.**\n\n| Ambiente | API | OAuth | `--env` |\n|----------|-----|-------|---------|\n| Produção | `api.kobana.com.br` | `app.kobana.com.br` | `production` (default) |\n| Sandbox | `api-sandbox.kobana.com.br` | `app-sandbox.kobana.com.br` | `sandbox` |\n| Development | `localhost:5005/api` | `localhost:5005` | `development` |\n\n```bash\n# Produção (default — não precisa de flag)\nkobana charge pix list\n\n# Sandbox\nkobana charge pix list --env sandbox\n\n# Development local\nkobana charge pix list --env development\n\n# Via variável de ambiente\nexport KOBANA_ENVIRONMENT=sandbox\nkobana charge pix list\n\n# Login em sandbox\nkobana auth login --env sandbox\n```\n\nOs tokens são **diferentes entre ambientes** — um token de sandbox não funciona em produção e vice-versa.\n\n## Uso\n\n### Sintaxe\n\n```bash\nkobana <servico> <recurso> <metodo> [flags]\n```\n\nServiços disponíveis:\n\n| Comando | Descrição |\n|---------|-----------|\n| `v1` | API v1 — boletos, clientes, webhooks |\n| `charge` | Cobranças — Pix, Pix automático |\n| `payment` | Pagamentos — boletos, Pix, taxas, concessionárias |\n| `transfer` | Transferências — Pix, TED, interna |\n| `financial` | Financeiro — contas, saldos, extratos |\n| `admin` | Administração — subcontas, usuários |\n| `mailbox` | Caixa postal — EDI, arquivos |\n| `data` | Consultas — boletos, QR codes Pix |\n| `security` | Tokens de acesso |\n\n### Exemplos\n\n```bash\n# Listar boletos com filtro\nkobana v1 bank-billets list \\\n  --params '{\"status\": \"opened\", \"per_page\": 25}' \\\n  --fields \"id,amount,status,due_at\"\n\n# Criar cobrança Pix\nkobana charge pix create \\\n  --json '{\"amount\": 99.90, \"pix_account_uid\": \"UID\"}'\n\n# Consultar saldo\nkobana financial accounts balances list \\\n  --params '{\"financial_account_uid\": \"UID\"}'\n\n# Transferência Pix\nkobana transfer pix create \\\n  --json '{\"amount\": 500, \"pix_key\": \"email@example.com\"}'\n\n# Listar com paginação automática (NDJSON)\nkobana charge pix list --page-all --fields \"uid,amount,status\"\n\n# Ver detalhes de um boleto\nkobana v1 bank-billets get --params '{\"id\": 12345}'\n\n# Cancelar boleto\nkobana v1 bank-billets cancel --params '{\"id\": 12345}'\n\n# Dry-run — ver a requisição sem executar\nkobana charge pix create --json '{\"amount\": 100}' --dry-run\n\n# Saída em tabela\nkobana v1 bank-billets list --output-format table\n\n# Salvar resposta em arquivo\nkobana v1 bank-billets get --params '{\"id\": 12345}' --output boleto.json\n```\n\n### Helpers\n\nAtalhos para operações comuns:\n\n```bash\n# Emitir boleto\nkobana +emitir --valor 150.50 --vencimento 2026-05-01 \\\n  --nome \"Maria Silva\" --cpf-cnpj \"012.345.678-90\" --carteira 1\n\n# Criar cobrança Pix\nkobana +cobrar --valor 99.90 --conta-pix \"UID\" \\\n  --nome \"João\" --cpf-cnpj \"012.345.678-90\"\n\n# Cancelar boletos em lote\nkobana +cancelar-lote --ids \"123,456,789\"\n```\n\n## Introspecção de Schema\n\n```bash\n# Listar todos os serviços e recursos\nkobana schema --list\n\n# Ver schema de um endpoint específico\nkobana schema charge.pix.create\nkobana schema v1.bank-billets.list\n```\n\nRetorna parâmetros, campos obrigatórios, tipos e respostas — tudo derivado do OpenAPI spec embutido.\n\n## Flags Globais\n\n| Flag | Descrição |\n|------|-----------|\n| `--params '<JSON>'` | Parâmetros de query/URL (id, page, filtros) |\n| `--json '<JSON>'` | Corpo da requisição (POST/PUT/PATCH) |\n| `--fields '<CAMPOS>'` | Limita campos na resposta |\n| `--dry-run` | Mostra a requisição sem executar |\n| `--page-all` | Auto-paginação com saída NDJSON |\n| `--page-limit <N>` | Máximo de páginas (default: 10) |\n| `--page-delay <MS>` | Delay entre páginas (default: 100ms) |\n| `--env <ENV>` | Ambiente: `production` (default), `sandbox`, `development` |\n| `--verbose` | Detalhes da requisição no stderr |\n| `--output <PATH>` | Salva resposta em arquivo |\n| `--output-format <FMT>` | Formato: `json`, `table`, `csv` |\n| `--idempotency-key <KEY>` | Chave de idempotência customizada |\n\n## Variáveis de Ambiente\n\n| Variável | Descrição |\n|----------|-----------|\n| `KOBANA_TOKEN` | Token de acesso Bearer |\n| `KOBANA_CREDENTIALS_FILE` | Caminho para arquivo JSON de credenciais |\n| `KOBANA_CLIENT_ID` | OAuth client ID |\n| `KOBANA_CLIENT_SECRET` | OAuth client secret |\n| `KOBANA_CONFIG_DIR` | Diretório de config (default: `~/.config/kobana`) |\n| `KOBANA_ENVIRONMENT` | `sandbox` (default) ou `production` |\n| `KOBANA_LOG` | Nível de log para stderr (ex: `kobana=debug`) |\n| `KOBANA_LOG_FILE` | Diretório para logs JSON com rotação diária |\n\nVariáveis também podem ser definidas em arquivo `.env`.\n\n## Códigos de Saída\n\n| Código | Significado |\n|--------|-------------|\n| `0` | Sucesso |\n| `1` | Erro de API (4xx/5xx) |\n| `2` | Erro de autenticação |\n| `3` | Erro de validação |\n| `4` | Erro de schema |\n| `5` | Erro interno |\n\n## Shell Completions\n\n```bash\n# Bash\nkobana completions bash > /etc/bash_completion.d/kobana\n\n# Zsh\nkobana completions zsh > ~/.zfunc/_kobana\n\n# Fish\nkobana completions fish > ~/.config/fish/completions/kobana.fish\n\n# PowerShell\nkobana completions powershell > kobana.ps1\n```\n\n## CI/CD & Releases\n\nO projeto usa GitHub Actions para CI e releases automatizadas.\n\n### CI\n\nToda push e PR na `main` executa:\n\n1. `cargo test` + `cargo clippy`\n2. Build cross-platform (Linux amd64/arm64, macOS amd64/arm64, Windows amd64)\n\n### Criar uma release\n\n1. Atualize a versão em `crates/kobana-cli/Cargo.toml` e `crates/kobana/Cargo.toml`\n2. Atualize o `CHANGELOG.md`\n3. Commit com prefixo `release:`:\n\n```bash\ngit add -A\ngit commit -m \"release: v0.2.0\"\ngit push\n```\n\nO workflow detecta o prefixo `release:` no commit message, compila os 5 targets e cria uma GitHub Release com os binários anexados.\n\n### Download de binários\n\nBinários pré-compilados estão disponíveis na [página de Releases](../../releases):\n\n| Plataforma | Arquivo |\n|------------|---------|\n| Linux x86_64 | `kobana-linux-amd64` |\n| Linux ARM64 | `kobana-linux-arm64` |\n| macOS Intel | `kobana-darwin-amd64` |\n| macOS Apple Silicon | `kobana-darwin-arm64` |\n| Windows x86_64 | `kobana-windows-amd64.exe` |\n\n## Arquitetura\n\n```\nkobana-cli/\n├── crates/\n│   ├── kobana/          # Biblioteca: HTTP client, error types, OpenAPI parsing, validação\n│   └── kobana-cli/      # Binário: CLI, auth, formatação, paginação, helpers\n│       └── specs/       # OpenAPI specs v1 e v2 embutidos\n└── docs/                # Especificações e documentação de design\n```\n\nComandos são gerados **dinamicamente** a partir dos OpenAPI specs da Kobana embutidos no binário. Atualizar a API = atualizar os specs + rebuild.\n\n## Licença\n\nMIT\n",
  "bytes": 8604,
  "sha": "b45faec440ddb35dce8033d0ae031b60b7defce70cc37eed94ae81ebf53210c9",
  "repo_slug": "universokobana/kobana-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_universokobana_kobana_cli_86cb3405/readme"
}