credithub-cli

credithub — CLI administrativo do CreditHub, no espírito do GitHub CLI (gh): administre contas, tags, faturas, relatórios e notificações do terminal, com saída legível para humanos e 100% operável por agentes de IA.

É uma aplicação GNU-like: executada sem argumentos, se explica; todo comando tem --help com exemplos e o endpoint BPQL que chama; há man page (man credithub). Se você é uma IA, comece por docs/ai-guide.md.

Instalação e primeiros passos

npm install -g @credithub/cli      # quando publicado no npm
# ou, a partir do repositório:
npm install && npm run build
node dist/bin.js            # ou: npm link && credithub

# autenticar (humano)
credithub auth login rafaelnasser123

# IA autentica SOZINHA (device flow): mostra código + link, o humano só
# aprova no navegador (Harlan) — sem bash, sem senha no chat
credithub auth login --device --agent "Claude Code / Fable5"

# formas diretas, declarando o operador — a identidade entra assinada no JWT
credithub auth login rafaelnasser123 senha123 "Claude Code / Fable5"
# código gerado por IA rodando numa plataforma/integração:
credithub auth login svc-x --with-api-key --agent "Claude Code / Fable5 / Salesforce"

O que ele faz

# contas
credithub user list --tag ouro --json
credithub user view cliente123
credithub user unblock cliente123 --reason "pagamento confirmado"
credithub user tag add cliente123 ouro

# faturas
credithub invoice issue cliente123
credithub invoice check-payment cliente123   # baixa no Banco Inter + desbloqueio

# Consulta Simples: dossiê de CPF/CNPJ (cadastro, dívidas, protestos, CCF,
# processos; --serasa/--boavista/--veiculos/--score-* opcionais)
credithub consulta 28.654.493/0001-00
credithub consulta 28654493000100 --serasa --wait --json

# auditoria: quem consultou o quê
credithub usage report --user cliente123 --from 2026-07-01 --json

# relatórios
credithub report consumption --user cliente123
credithub report all-users --due-date 10 > consumo.csv

# forçar push / mensagens
credithub push trigger inbound --user cliente123

# escape hatch (como `gh api`) e catálogo dinâmico
credithub api "SELECT FROM 'BipbopCompanys'.'List'" -f tag=ouro --collect company --json
credithub info --jq '.tools | length'

Fluxos em massa (pipes, como no gh)

# "preciso dos telefones de todos os +140 usuários da tag ouro"
credithub user list --tag ouro --all --json username,telefones > usuarios.ndjson

# "agora adiciona as tags X, Y e Z em todos que retornaram"
jq -r '.username' usuarios.ndjson | credithub user tag add - X Y Z --plan <id>

--all pagina até o fim em stream (NDJSON com --json); página única com --json traz envelope {total, limit, skip, nextSkip, items}; - no lugar do username lê um por linha do stdin.

IA propõe, humano aprova

Quando a sessão foi autenticada com identidade de agente (claim agent no JWT), mutações sensíveis não executam direto: viram passos de um plano com contexto ("vou fazer isso, isso e isso, por este motivo"), o administrador humano recebe e aprova (ou rejeita), e só então a IA executa:

credithub plan create --title "Regularizar cliente X" --context "..."
credithub user unblock cliente123 --plan <id>     # anexa, não executa
credithub plan submit <id>                        # humano recebe e revisa
credithub plan wait <id> && credithub plan run <id>

Detalhes em docs/design.md §5; mapa completo comando → endpoint em docs/commands.md; prompt do projeto em PROMPT.md.

Stack

TypeScript · Node ≥ 20 · @credithub/webservice como transporte BPQL · commander · Jest.