choliba run
Roda um agente da pasta de trabalho ou os testes E2E de um projeto. O tipo vem depois do verbo: agent ou tests.
Uso
choliba run TYPE [ARGS]Exemplos
Implementa o ticket loja-1:
choliba run agent implementer --project loja --ticket loja-1Roda os testes do projeto loja:
choliba run tests lojaagent
Executa um agente da pasta de trabalho (.choliba/agents/<nome>/) por um provider (auto, claude, claude-ollama, codex, cursor).
Uso
choliba run agent AGENT [OPTIONS] [TASK...]Exemplos
Escreve o ticket de uma story nova a partir de um pedido:
choliba run agent product-owner --project loja --type story "a busca aceita filtro por data"Escreve os testes do ticket loja-1:
choliba run agent test-writer --project loja --ticket loja-1Mostra o que a implementação faria, sem executar nada:
choliba run agent implementer --project loja --ticket loja-1 --dry-runDetalhes
As flags que um agente aceita dependem do agent.yaml dele: --project só para quem age num projeto, --type e --ticket só para quem tem ticket_types, --mode só com os modos que ele permite, --since só para quem tem um git_diff. choliba run agent <agente> --help mostra as do agente; a tabela abaixo tem todas. Uma execução passa pelo ciclo de execução: o choliba antes, o modelo, o choliba depois. Num terminal, a saída do agente vai num quadro, com o provider, o modelo, o sandbox e o tempo decorrido numa tabela no rodapé.
--dry-run
--dry-run mostra, na ordem, o que o comando faria sem ele, e não executa nada: nenhum step, nenhum ticket, nenhuma pasta de execução, nenhum provider. Vale em qualquer modo. Ele só lê o que precisa para montar a lista (o agent.yaml, as skills, os MCPs, o projeto e o ticket), então um problema que faria a execução falhar antes do agente aparece do mesmo jeito.
$ bun choliba run agent implementer --mode plan --dry-run --project app --ticket app-1
Sem --dry-run, faria nesta ordem:
1. [CLI] confere http://localhost:5173/: sem resposta, para aqui (o ambiente não tem envs[].start)
2. [CLI] plan.before 1/2 — run: bun choliba run tests app:app-1 --expect red --failures .cache/test-writer/app-1/red.md
se falhar: para aqui, o agente não roda
3. [CLI] plan.before 2/2 — read_files: tag=falhas_red files=.cache/test-writer/app-1/red.md
se falhar: para aqui, o agente não roda
4. [agente] cursor · modelo Composer 2.5 Fast · modo plan · na pasta .cache/runs/<id>
skills: playwright-trace · MCPs: nenhum
prompt de sistema: 8053 bytes · prompt do usuário: 218 bytes (--show-prompt mostra os dois)
comando: agent -p <prompt> --trust --disable-auto-update --output-format stream-json …
5. [CLI] plan.after.success (se o agente sair com 0): nada
plan.after.failure (se o agente falhar): nada
plan.after.always: nada
6. [CLI] fecha o ticket: apaga um ticket novo que o agente não preencheu; em execute, falha com CHANGE_ME ou fora do modeloCom --show-prompt (só junto de --dry-run), a saída segue com os dois prompts completos, a linha de comando completa (em JSON, um argumento por item) e, no Cursor, o .cursor/cli.json da pasta da execução e o .cursor/mcp.json da raiz, como seriam gravados.
Antes do agente, com --project, o choliba deixa a aplicação pronta: veja A aplicação do projeto.
Opções
| Opção | Descrição |
|---|---|
--mode <string> | Modo de execução (padrão: modes.default do agente):execute: Faz a tarefa, com as permissões que o agente declara.plan: Só planeja, sem gravar nada, e salva o plano em plans/ para rodar depois com --plan-from.ask: Só responde, sem gravar nada. |
--mode-execute | Atalho para --mode execute |
--mode-plan | Atalho para --mode plan |
--mode-ask | Atalho para --mode ask |
--project <name> | Projeto em CHOL_PROJECTS_DIR sobre o qual o agente age; validado antes de chamar o provider |
--type <type> | Tipo do ticket novo, criado pelo CLI a partir do template do tipo:bug: Correção de falha: a aplicação faz algo diferente do esperado.improvement: Ajuste em algo que já existe: fluxo, texto, usabilidade ou desempenho.story: Valor para o usuário: uma capacidade nova, descrita pelo que ele passa a conseguir fazer.task: Execução técnica, sem comportamento novo visível para o usuário. |
--type-bug | Atalho para --type bug |
--type-improvement | Atalho para --type improvement |
--type-story | Atalho para --type story |
--type-task | Atalho para --type task |
--ticket <key> | Ticket existente do projeto sobre o qual o agente trabalha |
--plan-from <file> | Executa um plano salvo (arquivo em plans/) |
--since <ref> | Base do diff: pending (desde a última execução registrada), HEAD~N, branch, tag ou SHA (padrão: base do git_diff do agente) |
--since-pending | Atalho para --since pending (desde a última execução registrada) |
--provider <string> | Provider que roda o agente (padrão: auto):auto: O primeiro provider que o agente declara e que está instalado, na ordem do agent.yaml.claude: Comando claude.claude-ollama: Comando claude, com um modelo do Ollama (declarado em agent.yaml#providers.claude-ollama) servido em CHOL_OLLAMA_URL.codex: Comando codex.cursor: Comando agent, cursor-agent ou cursor agent, o primeiro que estiver instalado. |
--auto | Atalho para --provider auto |
--claude | Atalho para --provider claude |
--claude-ollama | Atalho para --provider claude-ollama |
--codex | Atalho para --provider codex |
--cursor | Atalho para --provider cursor |
--model <string> | Modelo; precisa estar em models do agente |
--sandbox <string> | Onde o provider roda, só nesta execução (padrão: CHOL_SANDBOX):local: Nesta máquina, isolado com bwrapdocker: Num container do Docker |
--agents-dir <dir> | Pasta dos agentes (padrão: .choliba/agents/) |
--add-dir <dir> | Pasta extra que o agente pode ler (pode repetir); o deny do agente continua valendo |
--dry-run | Mostra o que seria executado, na ordem, sem executar nada |
--show-prompt | Com --dry-run: mostra os prompts e a linha de comando completos (e, no cursor, os arquivos de .cursor/) |
-h, --help | Mostra a ajuda do agente |
tests
Roda os testes E2E dos projetos com o Playwright. Sem projeto, roda todos; com projeto:ticket, só os daquele ticket.
Uso
choliba run tests [PROJECT[:TICKET][/PATH]] [OPTIONS] [PLAYWRIGHT OPTIONS]Exemplos
Roda os testes de todos os projetos:
choliba run testsRoda os testes de todos os tickets do projeto loja:
choliba run tests lojaRoda os testes do ticket loja-1:
choliba run tests loja:1Roda uma lista de tickets (também glob e intervalo):
choliba run tests loja:1,2Roda um arquivo do projeto:
choliba run tests loja/tests/a.spec.tsConfere que os testes do ticket falham pelo comportamento, gravando as falhas:
choliba run tests loja:1 --expect red --failures falhas.mdDetalhes
Antes de rodar, o choliba deixa a aplicação do projeto pronta: veja A aplicação do projeto. --expect e --failures são os portões que os agentes usam no TDD; os testes de critérios que outro ticket substituiu saem das rodadas do projeto. Os dois estão em Critérios de aceite e portões. Qualquer outra opção vai para o playwright test (veja bunx playwright test --help).
Opções
| Opção | Descrição |
|---|---|
--expect <red|green> | O que a execução de um ticket deve mostrar; falha se não mostrar |
--failures <file> | Grava em FILE como os testes do ticket falharam |
-h, --help | Mostra esta ajuda |
--no-color e --version valem em qualquer comando: veja Comandos.