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 — o PADRÃO é pelo navegador (device flow, como o gh):
# o CLI mostra código + link (e abre o navegador se houver TTY); você
# aprova no Harlan e a senha nunca passa pelo terminal
credithub auth login

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

# usuário+senha (só quando pedido explicitamente: username em argv,
# --with-password ou --totp) — a identidade entra assinada no JWT
credithub auth login rafaelnasser123
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>

A subchave do agente (device auth) carrega a delegação administrativa do master: foi emitida com a senha dele no painel, é identificada (cadeia de proveniência) e revogável a qualquer momento (credithub agent revoke) — por isso o agente executa operações administrativas diretamente, mesmo autenticando por apiKey. O plano continua sendo a governança das mutações sensíveis no CLI, e no plan run cada passo viaja com o approvalToken: o backend confere o passo aprovado EXATO (single-use) e grava na trilha "executado sob o plano N aprovado por Y".

Detalhes em docs/design.md §5; mapa completo comando → endpoint em docs/commands.md. Para Codex e outros agentes compatíveis, o pacote também inclui a skill reutilizável operate-credithub.

Para investigação patrimonial autorizada e geração de grafos de evidências, instale a skill investigacao-patrimonial descrita abaixo.

Skills para Codex, Claude Code e OpenClaw

O pacote inclui duas skills que seguem o padrão Agent Skills (SKILL.md):

• operate-credithub — operação administrativa do CLI (consultas, mutações, billing, auditoria).
• investigacao-patrimonial — investigação patrimonial ativa para cobrança, análise de crédito e compliance/background check, com grafo de evidências.

Instale primeiro o CLI e depois use o instalador embutido:

npm install -g @credithub/cli
credithub skill install --skill all --target all

Para instalar uma skill específica:

credithub skill install --skill operate-credithub --target all
credithub skill install --skill investigacao-patrimonial --target all

Alvos individuais:

credithub skill install --skill all --target codex      # ~/.agents/skills
credithub skill install --skill all --target claude     # ~/.claude/skills
credithub skill install --skill all --target openclaw   # ~/.openclaw/skills

Para atualizar uma instalação existente após atualizar o npm:

npm install -g @credithub/cli@latest
credithub skill install --skill all --target all --force

O padrão é uma instalação pessoal, disponível em todos os projetos. Para instalar apenas no diretório atual, acrescente --scope project; no OpenClaw, isso instala em ./skills/:

credithub skill install --skill all --target openclaw --scope project

Também é possível usar o instalador nativo do OpenClaw a partir de um clone deste repositório:

openclaw skills install ./skills/operate-credithub --global
openclaw skills install ./skills/investigacao-patrimonial --global

Confirmar e usar

Abra uma nova sessão do agente após a instalação. No Codex, execute /skills; no OpenClaw, execute openclaw skills list. Invoque explicitamente pelo nome:

$operate-credithub consulte a situação do CNPJ 00.000.000/0001-00
$investigacao-patrimonial investigue o patrimônio do CNPJ 00.000.000/0001-XX

No Claude Code, as skills também ficam disponíveis como /operate-credithub e /investigacao-patrimonial. Os agentes podem ativá-las automaticamente quando o pedido envolver o CreditHub ou investigação patrimonial.

Para remover:

credithub skill uninstall --skill all --target all

Stack

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