rockquant (CLI)

CLI oficial da RockQuant (rockquant). É um cliente MCP fino sobre a fachada mcp.rockquant.io (contrato: docs/architecture/17-MCP-F1-CONTRATO.md §5): não tem regra de domínio, e cada tool que a fachada anuncia vira um comando.

Instalação

Pacote npm rockquant, sem escopo (o escopo @rockquant no npm é de terceiros).

npm install -g rockquant      # ou, sem instalar: npx rockquant login

Modo interativo

rockquant sem argumentos, num terminal, abre o shell interativo: letreiro RockQuant, conta no cabeçalho, caixa de prompt e /comandos (/help, /login, /logout, /tools, /modelo, /trading, /nova, /sair e cada tool da fachada). Palavras depois do comando preenchem os campos obrigatórios da tool, na ordem do schema (/search_help circuit breaker, /get_help_article rocksense calibracao); --campo valor também vale. ↑↓ percorre o histórico, Tab completa, Ctrl+C sai. Em pipe (sem TTY), sem argumentos continua sendo erro de uso (exit 2).

Conversa com IA

Texto sem / é uma pergunta para a IA, que usa as tools por você. Toda tool que altera algo pede confirmação (s/n) antes de rodar; recusar volta ao modelo como recusa. Cada rodada é uma chamada ao modelo: uma pergunta que usa duas tools custa três chamadas, e o custo aparece no fim da resposta e no rodapé. Até 8 rodadas por pergunta.

• /modelo lista quem pode responder: RockAI com os créditos de cada produto, ou a sua chave própria (cadastrada no app) com o modelo que você escolher. /modelo <n> (ou só o número, logo depois da lista) escolhe, e a escolha fica em ~/.rockquant/config.json. Sem escolha, vale o RockAI do primeiro produto com saldo.
• /trading on (fonte RockBots) liga as propostas: alterações no RockBots viram proposta que você aprova no app. Pede o login do endpoint de trading na primeira vez. /trading off desliga.
• /nova começa uma conversa nova. O histórico só existe no processo da CLI.

A chamada ao modelo passa pela fachada: nenhuma chave de LLM fica no cliente, e nada da conversa é guardado no servidor.

Uso

rockquant login               # abre o navegador; --no-browser só imprime a URL
rockquant whoami --json
rockquant tools
rockquant search_help --query "parear engine" --json
rockquant get_help_article --input args.json   # flags na linha de comando prevalecem sobre o arquivo
rockquant list_strategies                     # nomes e ids das suas estratégias
rockquant run_backtest --strategy-id "Minha 9.3" --symbols WINFUT --timeframe 15m \
  --start 2025-01-02 --end 2025-06-30 --initial-cash 100000 --lot-count 1 --wait
rockquant list_optimizable_params --backtest-job-id <job_id>
rockquant run_optimization --backtest-job-id <job_id> \
  --param-ranges '{"strategy.risk.stop_loss_points":{"min":50,"max":200,"step":10}}' --wait
rockquant run_wfa --backtest-job-id <job_id> --n-windows 5 --wait
rockquant run_monte_carlo --backtest-job-id <job_id> --wait
rockquant rockbots_desk_results --from 2026-09-01 --to 2026-09-30   # relatório da mesa
rockquant rockbots_list_missions --status open                      # missões abertas
rockquant rocksense_get_panel --period 24h                         # leitura do RockSense
rockquant logout

• --kebab-case vira o campo do inputSchema da tool (--dry-run → dry_run ou dryRun). Valor que é JSON válido vira JSON, exceto em campo string. Flag sem valor = true. Campo lista aceita array JSON ou valores separados por vírgula ou espaço (--symbols WIN$N,WDO$N).
• run_backtest --wait acompanha cada job até COMPLETED, FAILED ou CANCELED. No terminal mostra o progresso e as métricas no fim; com --json devolve os jobs com o status final. No modo interativo, /run_backtest sempre acompanha.
• run_optimization, run_wfa e run_monte_carlo também aceitam --wait: acompanham a validação até o fim e, no terminal, mostram o resultado (na otimização, os melhores candidatos). No modo interativo, sempre acompanham.
• Séries contínuas aceitam WINFUT ou WIN$N na entrada e aparecem como WINFUT na tela; o JSON mantém symbol (WIN$N) e traz display_symbol (WINFUT).
• RockBots: rockbots_desk_results aceita data simples (dia inteiro em Brasília) e mostra o período ao lado do anterior de mesma duração, por agent, ativo e dia. Agents, missões e engines saem em tabela. Alterar o RockBots (missões, agents, risco, pausar, zerar) só pelo endpoint de trading, com --trading antes do comando (login próprio: rockquant --trading login). Ali cada alteração vira uma proposta: nada roda até você aprovar no app (RockBots › Propostas). Acompanhe com rockquant --trading rockbots_get_proposal --proposal-id <id> ou rockbots_list_proposals.
• Num terminal, sem --json, a resposta sai formatada para leitura (sem cor com NO_COLOR). Em pipe, sem --json, sai o texto da tool, como antes.
• --json imprime {schema_version: 1, ...structuredContent} no stdout. Logs e erros vão para o stderr.
• Exit codes: 0 ok · 1 upstream · 2 invalid_input · 3 unauthorized (rode login) · 4 not_entitled · 5 rate_limited · 6 not_found.

Sessão

• ROCKQUANT_MCP_URL escolhe a fachada (padrão https://mcp.rockquant.io; local: http://localhost:8787, o mesmo host de MCP_PUBLIC_URL, porque o iss tem que bater).
• Login OAuth com o client público rockquant-cli: PKCE S256 e callback em http://127.0.0.1:<porta livre>/callback.
• --trading usa o recurso /trading da fachada, com credencial própria em ~/.rockquant/credentials-trading.json: o token de um endpoint não vale no outro.
• A credencial fica em ~/.rockquant/credentials.json (0600 no POSIX) e só é usada para a mesma base_url em que foi emitida. O access token é renovado quando faltam menos de 5 min; se o refresh for recusado (invalid_grant), o arquivo é apagado e a CLI sai com 3.

Desenvolvimento

pnpm --filter rockquant build       # dist/cli.mjs (build.mjs: esbuild com React/Ink embutidos)
cd apps/cli && pnpm typecheck && pnpm test

O npm publish roda o build sozinho (prepublishOnly). Os testes sobem uma fachada fake em node:http (AS + MCP, test/fake-server.ts), sem rede.