Como migrar um agente de programação no cron de um CLI para outro

Trocar o CLI que roda um agente de programação no cron parece uma linha: você muda o binário e mantém o prompt. Na prática, quebram cinco camadas, e nenhuma delas é o prompt. A gente viveu essa migração em 05/11/2026, quando a esteira que publica este blog saiu de um CLI de agente para a Verboo Code. O que segue é o que quebrou e o comando que resolve cada camada, verificado no código de verbeux-ai/code v0.15.41.

Resposta curta: reconfira o modo não interativo (-p), a autenticação sem navegador, o diretório de configuração (~/.verboo), o runtime (engines.node) e o protocolo das ferramentas MCP. Se qualquer uma dessas cinco continuar "emprestada" do CLI antigo, a migração não terminou.

Por que trocar o CLI do agente não é só trocar o comando?

Porque o comando é uma linha, mas o ambiente em volta não é. Um agente que roda sozinho, disparado por cron, depende de cinco camadas que o CLI antigo resolvia calado. Ao trocar o binário, cada uma delas pode parar de funcionar sem aviso:

• Modo não interativo. O cron não tem terminal. Se o CLI novo não tem um jeito de rodar sem perguntar nada, ele trava na primeira confirmação.
• Autenticação. O cron não tem navegador. Se o login do CLI novo depende de abrir uma página, a sessão nunca nasce.
• Diretório de configuração. Comandos, skills e permissões moram numa pasta que provavelmente não é a mesma do CLI antigo.
• Runtime. Cada pacote declara a versão de Node que suporta, e é fácil instalar num servidor que não bate.
• Ferramentas externas. Servidores MCP conversam por protocolo. Cliente e servidor precisam falar a mesma revisão.

Como provar que o CLI novo roda sem terminal?

Antes de tocar em qualquer script, rode o binário com um prompt inofensivo e peça saída em JSON. Se isso voltar, o contrato de modo não interativo está de pé:

verboo -p "responda apenas: ok" --output-format json

-p (ou --print) imprime a resposta e sai, útil para pipe. O --output-format só funciona junto com -p e aceita text (padrão), json (um resultado único) ou stream-json (eventos em tempo real). Num cron você quer json: um objeto por execução, fácil de registrar num log.

Três flags fecham o comportamento de um job desatendido. --max-turns limita quantas idas e voltas o agente dá antes de parar, para o job não ficar pendurado. --max-budget-usd impõe um teto de gasto por execução. E --no-session-persistence impede que a rodada seja gravada em disco, o que evita um cron diário acumulando sessões que ninguém vai retomar. Vale saber também que, em -p, o diálogo de confiança do diretório de trabalho é pulado, então aponte o job só para pastas em que você confia.

Onde fica a autenticação quando não existe navegador?

O cron não abre navegador, então o login interativo padrão não serve. O Verboo Code resolve isso por dois caminhos, e a escolha depende de onde o job roda:

Caminho	Como funciona	Quando usar
verboo auth login --headless	Sem navegador: mostra uma URL para abrir em outro dispositivo e pede um código de volta	Máquina que você controla e onde a sessão pode ficar salva
ANTHROPIC_API_KEY	Chave de API passada por variável de ambiente, sem sessão OAuth	Runner efêmero de CI ou container que morre no fim do job

No caso da chave, o valor é ANTHROPIC_API_KEY mesmo, não uma variável com outro nome. Quem configurar isso está guardando credencial no ambiente, então o mínimo é não imprimir a variável no log e restringir quem lê a config do job.

Por que a configuração antiga contamina o job novo?

Porque o CLI novo não lê a pasta do CLI antigo. O Verboo Code guarda tudo em ~/.verboo, e o código diz explicitamente que não lê nem migra arquivo global de outro CLI. Na prática isso significa que os seus comandos, skills e permissões não vêm de graça: skills ficam em ~/.verboo/skills, comandos em ~/.verboo/commands e as permissões em ~/.verboo/settings.json. Copiar a pasta inteira de um CLI para o outro não funciona, porque o formato é outro.

A exceção, e ela é de propósito, é o diretório de sessões. Por padrão ele continua em ~/.claude/projects, justamente para permitir --resume entre CLIs. Se você quiser isolamento total, é só apontar outra pasta. E se mais de um job roda na mesma máquina, o caminho mais limpo é dar a cada um o seu próprio diretório de configuração:

export VERBOO_CONFIG_DIR=/opt/jobs/blog/.verboo
verboo -p "sincronize os drafts" --output-format json

Assim o job tem a própria chave, as próprias permissões e o próprio histórico, sem competir com a sessão interativa da mesma máquina.

Qual runtime o pacote exige?

Instale pensando na versão de Node, não só na versão do CLI. O pacote @verboo/code declara engines.node >= 22.0.0. Confira antes de instalar num servidor antigo:

node -v
npm install -g @verboo/code
verboo --version

Se o node -v voltar 20, o caminho mais curto é subir o Node antes de brigar com o npm install. O erro de engine aparece no meio da instalação e parece outra coisa.

Como saber se as ferramentas MCP chegaram?

Pelo sintoma, que é silencioso. Quando a revisão do protocolo do cliente e a do servidor não batem, o handshake falha, a lista de ferramentas volta vazia e o agente simplesmente "não usa" a ferramenta. Não há erro barulhento: o prompt roda, a saída sai, e a ação que dependia daquela ferramenta nunca acontece.

Então confira a lista antes de culpar o prompt. Para fixar exatamente quais servidores entram no job, use --mcp-config com os arquivos certos e --strict-mcp-config, que ignora qualquer outra configuração de MCP que esteja na máquina. Um job de cron deve rodar sempre com a mesma lista de servidores, nunca com a que estava por acaso no diretório.

O que conferir antes de desligar o CLI antigo?

Rode os dois em paralelo por alguns dias e compare a saída, não a sensação. O critério de "terminei a migração" é objetivo:

1. O job roda duas vezes seguidas sem ninguém tocar, e o artefato final sai igual ao do CLI antigo.
2. O log de cada execução registra quantas ferramentas foram chamadas e quais.
3. Uma execução simulada de falha (chave inválida, rede fora) termina com erro claro, não com um job pendurado.
4. O node -v do servidor bate com o engines.node do pacote.
5. Nenhuma etapa ainda depende de um arquivo que só existia na pasta do CLI antigo.

Se os cinco baterem, você migrou. Se algum depender do CLI velho, é ali que o próximo job vai quebrar sozinho, num fim de semana.