Modulo 1.4 - Criando sua propria CLI

🪄 Comando /printing-press

Dentro do Claude Code, voce dispara o pipeline com um slash command. O agente conduz a entrevista, voce so confirma e ajusta.

Disparar

# Modo URL
/printing-press https://brasilapi.com.br

# Modo nome (procura no library oficial primeiro)
/printing-press brasil-api

# Modo blank
/printing-press
> Qual sistema voce quer transformar em CLI?

📋 O que o factory pergunta

· Nome da CLI (sera <nome>-pp-cli)
· Nome da skill (sera pp-<nome>)
· Endpoints prioritarios
· Tem auth? Qual tipo (API key, OAuth, Bearer)?
· Output padrao (texto humano ou JSON)?

🔎 Fase research

O factory navega na doc oficial, le SDKs em npm/pip, busca exemplos em blogs e captura endpoints. Tudo vai para research/ para voce revisar.

Artefatos gerados

research/
├── endpoints.yaml       # lista de URLs descobertos
├── auth.md              # como autenticar
├── schemas/             # tipos das respostas
│   ├── post.json
│   └── user.json
├── examples/            # curl reais que funcionaram
└── notes.md             # achados e armadilhas

💡 Revise antes de avancar

Editar endpoints.yaml nesta fase economiza horas depois. Remova endpoints internos, marque deprecados, comente quotas conhecidas.

🧠 Fase generate

Com a research aprovada, o factory gera codigo Go usando Cobra (CLI), estruturas de resposta e templates de output. O codigo gerado e legivel e segue convencoes.

Estrutura tipica

brasil-api-pp-cli/
├── cmd/
│   ├── root.go
│   ├── cep.go
│   ├── cnpj.go
│   └── bancos.go
├── internal/
│   ├── client/          # http client + retries
│   ├── cache/           # SQLite mirror
│   └── format/          # templates de output
├── skills/pp-brasil-api/
│   └── SKILL.md
├── printingpress.yaml   # manifesto
└── go.mod

⏸️ Voce pode pausar

Antes de compilar, dt-se ao luxo de revisar templates de output. E o detalhe que define a UX final que o agente entrega.

✅ Verify e score (Steinberger bar)

Bateria automatica de testes mais score por criterios objetivos. CLI com nota baixa nao entra no library oficial.

Rodar verify

$ printing-press verify
running 28 smoke tests...

[OK] cep: 01310100 retorna avenida paulista
[OK] cnpj: 00000000000191 retorna BCB
[OK] bancos: lista contem itau (3 ms cache)
[OK] feriados: 2025 contem natal
[FAIL] ddd: 11 timeout 5s
...
Score: 87/100  (minimo library: 80)

Criterios do Steinberger bar

Criterio	Peso	Foco
Reliability	30%	Smoke tests passam, retries, timeout
Token efficiency	25%	Tamanho do output medio vs JSON cru
Docs	15%	README, SKILL.md, exemplos
Schema stability	15%	Output versionado, NDJSON estavel
UX	15%	Mensagens de erro claras, --help util

🕵️ browser-sniff e crowd-sniff

Quando o alvo nao tem API publica, o factory tem dois "modos espertos" para descobrir endpoints.

🌐 browser-sniff

Voce navega no site logado e o factory captura o trafego (HAR file ou devtools).

/printing-press https://skool.com \
  --mode browser-sniff \
  --har ./capture.har

Bom para: SaaS sem API, intranets, sites com login.

📚 crowd-sniff

Minera SDKs publicos em npm/pip/RubyGems do mesmo servico e extrai endpoints.

/printing-press notion \
  --mode crowd-sniff

Bom para: APIs com doc fraca mas SDK oficial maduro.

⚠️ Etica e ToS

Browser-sniff de servicos privados respeita ToS. Use so onde voce tem conta e direito de acesso. CLIs publicadas no library nao podem violar termos de uso do alvo.

🔐 Auth, polish e shipcheck

Tres comandos finais antes da CLI estar pronta para o library: configurar credenciais, refinar UX e validar o pacote.

Pipeline de finalizacao

# Configurar credenciais (salva em keychain do SO)
$ printing-press auth --cli brasil-api
> Tem chave de API? (s/N) N
> OK, BrasilAPI nao requer auth. Pulando.

# Polir mensagens, cor, --help, alias
$ printing-press polish

# Validar tudo antes de publicar
$ printing-press shipcheck
[OK] manifesto valido
[OK] smoke tests passam
[OK] score >= 80 (87)
[OK] SKILL.md tem >= 3 exemplos
Ready to publish.

💡 O que o polish faz

Aplica padroes do library: cor consistente, mensagens de erro padronizadas, --help verboso, suporte a --json em todos os comandos, exit codes corretos.

✅ Resumo do Modulo

✓

Pipeline em 6 fases — start, research, generate, verify, polish, shipcheck.

✓

Research e revisavel — voce edita endpoints.yaml antes de gerar codigo.

✓

Steinberger bar >= 80 — requisito para entrar no library.

✓

browser-sniff e crowd-sniff — quando o alvo nao tem API publica.

Proximo Modulo:

1.5 — Caso pratico: construir a brasil-api-pp-cli do zero

← Modulo anterior Proximo Modulo →