# opencode-ralph-loop-cli
[](https://crates.io/crates/opencode-ralph-loop-cli)
[](https://docs.rs/opencode-ralph-loop-cli)
[](https://github.com/daniloaguiarbr/opencode-ralph-loop-cli/actions/workflows/ci.yml)
[](LICENSE-MIT)
[](https://crates.io/crates/opencode-ralph-loop-cli)
> "Um comando monta toda a configuração do plugin OpenCode Ralph Loop."
Leia em [English](README.md).
## O que é?
- Gera a estrutura completa `.opencode/` em um único comando determinístico
- Embute seis arquivos de template como bytes estáticos — zero chamadas de rede em runtime
- Verifica idempotência via SHA-256: arquivos inalterados nunca são sobrescritos
- Suporta saída JSON e NDJSON para pipelines automatizados por agentes
- Rastreia arquivos instalados via `.manifest.json` para remoção limpa pelo `uninstall`
- Diagnostica dependências do ambiente pelo subcomando `doctor`
## Por que usar?
- Saia do zero ao Ralph Loop funcionando em menos de 10 segundos em qualquer plataforma
- Saída determinística garante bytes idênticos em cada execução e cada máquina
- Contrato JSON legível por máquina parseia corretamente com `jq` sem configuração adicional
- Detecção de conflitos previne perda acidental de dados antes de `--force` ser necessário
## Superpoderes para Agentes de IA
| Claude Code | Native CLI subprocess | latest |
| Codex (OpenAI) | Shell tool call | latest |
| Gemini CLI | Shell tool call | latest |
| Opencode | Native plugin host | latest |
| Cursor | Terminal tool | latest |
| Windsurf | Terminal tool | latest |
| VS Code Copilot | Task runner | latest |
| GitHub Copilot | Shell tool call | latest |
| Google Antigravity | Shell tool call | latest |
| Zed AI | Terminal tool | latest |
| Aider | Shell command | latest |
| Jules | Shell tool call | latest |
| Kilo Code | Shell tool call | latest |
| Roo Code | Shell tool call | latest |
| Cline | Shell tool call | latest |
| Continue | Shell tool call | latest |
| Factory AI | Shell tool call | latest |
| Augment Code | Shell tool call | latest |
| Minimax AI | Shell tool call | latest |
| Z.ai | Shell tool call | latest |
| JetBrains AI Assistant | Terminal tool | latest |
- Stdout determinístico permite que agentes parseem o output de forma confiável sem heurísticas
- Exit codes tipados permitem que agentes ramifiquem por conflito, drift ou erros de I/O com precisão
- Contrato JSON (`--output json`) fornece schema estável consumível por qualquer agente
- Zero dependências de runtime eliminam fricção de configuração de ambiente nos fluxos de agentes
- Idempotência garante re-execução segura dentro de loops e pipelines de retry
- Binário único multiplataforma elimina requisitos de interpretador ou runtime
## Início Rápido
```bash
cargo install opencode-ralph-loop-cli
opencode-ralph-loop-cli init
cd .opencode && bun install
```
## Comandos
### init
- `--path <DIR>` diretório alvo, padrão é o diretório de trabalho atual
- `--force` sobrescreve arquivos que diferem dos templates embutidos
- `--dry-run` simula sem escrever nada em disco
- `--plugin-version <VER>` sobrescreve a versão embutida do `@opencode-ai/plugin`
- `--no-package-json` suprime geração do `package.json`
- `--no-gitignore` suprime geração do `.gitignore`
- `--no-manifest` suprime geração do `.manifest.json`
- `--output <FORMAT>` formato de saída: `text`, `json`, `ndjson`, `quiet`
### check
- `--path <DIR>` diretório a auditar contra os templates embutidos
- `--strict` falha no primeiro drift detectado (exit code 5)
- `--exit-zero` força exit code 0 independente de drift encontrado
- `--output <FORMAT>` formato de saída: `text`, `json`, `ndjson`, `quiet`
### uninstall
- `--path <DIR>` diretório alvo para remoção do scaffold
- `--dry-run` simula remoção sem apagar nenhum arquivo
- `--force` prossegue mesmo sem `.manifest.json`
- `--keep-state` preserva `ralph-loop.local.md` durante a remoção
### list
- Lista os seis templates embutidos com hash SHA-256 e tamanho em bytes
### doctor
- Verifica presença de `bun`, `node` e `opencode` no PATH
- Reporta validade do manifest e integridade de cada arquivo contra os hashes embutidos
### completions
- `completions <shell>` gera script de autocomplete para bash, zsh, fish, powershell ou elvish
## Variáveis de Ambiente
| `OPENCODE_RALPH_LOOP_CLI_OUTPUT` | Formato de saída padrão | `text` |
| `OPENCODE_RALPH_LOOP_CLI_FORCE` | Habilita modo force | não definida |
| `OPENCODE_RALPH_LOOP_CLI_PLUGIN_VERSION` | Sobrescreve versão do plugin | `1.4.7` |
| `OPENCODE_RALPH_LOOP_CLI_CONFIG` | Caminho para arquivo de config alternativo | padrão XDG |
| `NO_COLOR` | Desabilita cores ANSI (padrão comunitário) | não definida |
| `RUST_LOG` | Filtro de log do tracing para diagnósticos verbosos | não definida |
## Códigos de Saída
| `0` | Sucesso |
| `1` | Erro genérico de execução |
| `2` | Argumento CLI inválido ou uso incorreto |
| `3` | Conflito de arquivo sem `--force` |
| `4` | Erro de I/O ou permissão negada |
| `5` | Drift detectado em modo `--strict` |
| `6` | Manifest ausente ou corrompido |
| `7` | Erro de parsing do arquivo de configuração |
| `130` | Interrompido por SIGINT |
## Instalação
- Instale pelo crates.io: `cargo install opencode-ralph-loop-cli`
- Baixe binários pré-compilados nos GitHub Releases quando o repositório estiver público
- Verifique a instalação: `opencode-ralph-loop-cli --version`
## Padrões de Integração
- Inspecione apenas arquivos com drift: `opencode-ralph-loop-cli check --output json | jq '.files[] | select(.action != "skipped")'`
- Falhe o CI em qualquer drift: `opencode-ralph-loop-cli check --strict --output quiet`
- Automatize no GitHub Actions: adicione `opencode-ralph-loop-cli check --strict` como etapa após o checkout
- Use em Makefile: `init: opencode-ralph-loop-cli init --dry-run && opencode-ralph-loop-cli init`
- Force reinit em scripts de reset: `opencode-ralph-loop-cli uninstall --force && opencode-ralph-loop-cli init --force`
- Transmita eventos NDJSON para um agregador de logs: `opencode-ralph-loop-cli init --output ndjson | tee init.log`
## Performance
- Tamanho do binário abaixo de 5 MB em todas as plataformas suportadas (stripped, LTO habilitado)
- Inicialização abaixo de 50 ms incluindo verificações de integridade SHA-256
- Zero chamadas de rede durante init, check, list e uninstall
- Escritas atômicas de arquivo previnem estado parcial em caso de interrupção do processo
## Solução de Problemas
### Conflito sem --force (exit 3)
- Um arquivo em `.opencode/` foi modificado desde o último `init`
- Execute `opencode-ralph-loop-cli check` para inspecionar quais arquivos diferem
- Use `--force` para sobrescrever com o conteúdo canônico do template
### Manifest ausente ou corrompido (exit 6)
- `.opencode/.manifest.json` está ausente ou contém JSON inválido
- Execute `opencode-ralph-loop-cli init` para regenerar o manifest
- Use `opencode-ralph-loop-cli uninstall --force` para ignorar a verificação do manifest
### Erro de I/O ou permissão negada (exit 4)
- O diretório alvo não existe ou não tem permissão de escrita
- Crie o diretório antes e tente novamente
- Verifique com `opencode-ralph-loop-cli init --path <DIR> --dry-run`
### doctor reporta bun não encontrado
- Instale o Bun em `bun.sh` e confirme que está no seu PATH
- Alternativamente use `node` e `npm install` dentro de `.opencode/`
### Saída JSON contém texto inesperado
- Use `--output json` explicitamente e valide com `jq '.'`
- Confirme que `--verbose` NÃO está ativo — saída verbose vai apenas para stderr
## Contribuindo
Veja [CONTRIBUTING.md](CONTRIBUTING.md) para configuração de desenvolvimento, estratégia de branches e checklist de PR.
## Segurança
Veja [SECURITY.md](SECURITY.md) para a política de divulgação de vulnerabilidades e cronograma de resposta.
## Código de Conduta
Veja [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) para os padrões da comunidade.
## Changelog
Veja [CHANGELOG.md](CHANGELOG.md) para o histórico completo de releases.
## Licença
- Licenciado sob MIT OR Apache-2.0 à sua escolha
- Veja [LICENSE-MIT](LICENSE-MIT) e [LICENSE-APACHE](LICENSE-APACHE) para os textos completos