Reverso CLI

CLI do agente investigativo Reverso — OSINT com LLM. Processa documentos, gera entendimento e conduz investigações com leads, allegations e findings rastreáveis.

Instalação

Recomendado — instalação global (evita conflitos com dependências do projeto):

# npm
npm install -g @reverso-agent/cli

# pnpm
pnpm add -g @reverso-agent/cli

Para usar como dependência local do projeto, use --ignore-scripts (a dependência yargs pode falhar em scripts de build em alguns ambientes):

npm i @reverso-agent/cli --ignore-scripts
# ou
pnpm add @reverso-agent/cli --ignore-scripts

Requisitos: Node.js >= 18.

Verificar:

reverso --version
reverso --help

Configuração

É obrigatória uma chave de API do OpenRouter. Use uma das opções abaixo (em ordem de prioridade):

Opção A — Variável de ambiente (recomendado)

export OPENROUTER_API_KEY=sk-...
# ou adicione ao ~/.zshrc / ~/.bashrc

Opção B — Arquivo global

mkdir -p ~/.reverso
echo "OPENROUTER_API_KEY=sk-..." > ~/.reverso/.env

Opção C — Por projeto

Crie um arquivo .env na pasta da investigação com OPENROUTER_API_KEY=sk-....

Modelo padrão: google/gemini-2.5-flash (alterável via --model onde disponível).

Primeiros passos

Fluxo recomendado numa pasta de investigação:

1. init — Lê previews em .artifacts (a partir de sources/, source/ ou root), gera entendimento inicial e cria agent.md.
2. agent-setup — Ajusta instruções do agente (ex.: foco em pessoa ou tema).
3. dig — Encontra possíveis leads a partir dos previews (top 3 sugestões, comparação com leads existentes).
4. create-lead — Registra um lead com Inquiry Plan em investigation/leads.
5. inquiry — Executa a investigação do lead e gera allegations/findings e conclusão.

O CLI detecta automaticamente a pasta de investigação e as fontes (ordem padrão: sources/, source/, depois PDFs no root). Para forçar um caminho: reverso --filesystem /caminho/para/root <comando>.

Exemplo completo

mkdir minha-investigacao && cd minha-investigacao
mkdir sources
# Copie PDFs para sources/ (ou deixe os PDFs no root)

reverso process-all                # processa PDFs e gera previews
reverso init                       # gera entendimento
reverso agent-setup --text "Foco na pessoa X"
reverso dig                        # encontra leads
reverso create-lead --idea "cartel combinacao"
reverso inquiry --lead cartel-combinacao

Comandos

• reverso setup — Setup guiado do workspace investigativo e configuração inicial.
• reverso process — Alias de alto nível: detecta PDFs em sources/, source/ ou root e dispara process-all.
• reverso process-all — Processa todos os PDFs pendentes.
• reverso process-selected — Processa apenas PDFs selecionados no checkpoint.
• reverso process-queue — Processa apenas documentos já enfileirados.
• reverso queue-status — Mostra a fila de processamento.
• reverso queue-clear — Limpa a fila (inteira ou por --files).
• reverso watch — Observa a pasta de fontes e atualiza checkpoint/queue.
• reverso select — Marca/desmarca PDFs para process-selected.
• reverso rerun — Limpa artefatos do modo e reprocessa (--all ou --input).
• reverso init — Entendimento inicial a partir dos previews. Saída: agent.md.
• reverso agent-setup — Atualiza agent.md com novas instruções (--text "...").
• reverso dig — Deep-dive nos previews, sugere leads. Saída: relatório em reports/dig-<timestamp>.md.
• reverso create-lead — Cria lead com Inquiry Plan (--idea "..." opcional). Saída: investigation/leads/lead-<slug>.md.
• reverso inquiry — Executa a investigação de um lead. Saída: allegations, findings e conclusão no lead.
• reverso inquiry-all — Executa investigação em lote para múltiplos leads no contexto atual.
• reverso doc-process — Namespace legado para compatibilidade (reverso doc-process <subcomando>). Prefira comandos diretos.

Flags globais: --filesystem <path>, --feedback plain|compact|visual (padrão: visual). Use reverso <comando> --help para opções de cada comando.

Saídas esperadas

Estrutura típica após o fluxo (relativa ao root da investigação):

• init / agent-setup: agent.md
• dig: reports/dig-<timestamp>.md
• create-lead: investigation/leads/lead-<slug>.md
• inquiry: investigation/allegations/*.md, investigation/findings/*.md, e conclusão atualizada no lead

Troubleshooting

• Erro DOMMatrix is not defined no reverso process
  • Causa comum: parsing local de PDF grande em ambiente sem suporte de runtime para canvas/DOMMatrix.
  • Mitigacao imediata: rode em modo OCR deep.

reverso process --mode deep
# ou
reverso process-all --mode deep

• Processamento parece "travado"
  • Veja o status da fila com reverso queue-status.
  • Para limpar fila antiga: reverso queue-clear.

Publicação e atualização sem navegador

Pacote scoped (@reverso-agent/cli). Para fluxo nao interativo, use token granular no ambiente:

export NPM_TOKEN=npm_xxxxxxxxx

O token deve ter permissao de publish e bypass de 2FA.

Guia completo (login, 2FA/OTP, erros comuns, CI): PUBLISH-NPM.md.

Resumo do ciclo oficial:

cd lab/agent-cli
pnpm run release:publish-global

Este comando executa: typecheck -> build -> check README/help -> version patch -> publish -> npm i -g @reverso-agent/cli@latest -> reverso --version/--help.