# 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)
> "One command scaffolds the complete OpenCode Ralph Loop plugin setup."
Read this in [Português](README.pt-BR.md).
## What is it?
- Generates the complete `.opencode/` structure in a single deterministic command
- Embeds six canonical template files as static bytes — zero network calls at runtime
- Verifies idempotency via SHA-256: unchanged files are never overwritten
- Supports JSON and NDJSON output for agent-driven pipelines
- Tracks installed files via `.manifest.json` for clean removal via `uninstall`
- Diagnoses environment dependencies via the `doctor` subcommand
## Why?
- Go from zero to a working Ralph Loop in under 10 seconds on any platform
- Deterministic output guarantees identical bytes on every run and every machine
- Machine-readable JSON contract parses cleanly with `jq` without extra configuration
- Conflict detection prevents accidental data loss before `--force` is required
## Superpowers for AI Agents
| 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 |
- Deterministic stdout enables agents to parse output reliably without heuristics
- Typed exit codes allow agents to branch on conflict, drift, or I/O errors precisely
- JSON contract (`--output json`) provides a stable schema consumable by any agent
- Zero runtime dependencies eliminate environment setup friction for agent workflows
- Idempotency guarantees safe re-execution inside loops and retry pipelines
- Single cross-platform binary removes interpreter or runtime requirements
## Quick Start
```bash
cargo install opencode-ralph-loop-cli
opencode-ralph-loop-cli init
cd .opencode && bun install
```
## Commands
### init
- `--path <DIR>` target directory, default is current working directory
- `--force` overwrite files that differ from the embedded templates
- `--dry-run` simulate without writing anything to disk
- `--plugin-version <VER>` override the embedded `@opencode-ai/plugin` version
- `--no-package-json` skip `package.json` generation
- `--no-gitignore` skip `.gitignore` generation
- `--no-manifest` skip `.manifest.json` generation
- `--output <FORMAT>` output format: `text`, `json`, `ndjson`, `quiet`
### check
- `--path <DIR>` directory to audit against embedded templates
- `--strict` fail at the first drift detected (exit code 5)
- `--exit-zero` force exit code 0 regardless of drift found
- `--output <FORMAT>` output format: `text`, `json`, `ndjson`, `quiet`
### uninstall
- `--path <DIR>` target directory to remove scaffold from
- `--dry-run` simulate removal without deleting any files
- `--force` proceed even if `.manifest.json` is missing
- `--keep-state` preserve `ralph-loop.local.md` during removal
### list
- Lists all six embedded templates with SHA-256 hash and byte count
### doctor
- Checks `bun`, `node`, and `opencode` presence in PATH
- Reports manifest validity and per-file integrity against embedded hashes
### completions
- `completions <shell>` generates completion script for bash, zsh, fish, powershell, or elvish
## Environment Variables
| `OPENCODE_RALPH_LOOP_CLI_OUTPUT` | Default output format | `text` |
| `OPENCODE_RALPH_LOOP_CLI_FORCE` | Enable force mode | unset |
| `OPENCODE_RALPH_LOOP_CLI_PLUGIN_VERSION` | Override plugin version | `1.4.7` |
| `OPENCODE_RALPH_LOOP_CLI_CONFIG` | Path to alternative config file | XDG default |
| `NO_COLOR` | Disable ANSI colors (community standard) | unset |
| `RUST_LOG` | Tracing log filter for verbose diagnostics | unset |
## Exit Codes
| `0` | Success |
| `1` | Generic runtime error |
| `2` | Invalid CLI argument or usage |
| `3` | File conflict without `--force` |
| `4` | I/O error or permission denied |
| `5` | Drift detected in `--strict` mode |
| `6` | Manifest missing or corrupted |
| `7` | Config file parse error |
| `130` | Interrupted by SIGINT |
## Installation
- Install from crates.io: `cargo install opencode-ralph-loop-cli`
- Download pre-built binaries from GitHub Releases once repository is public
- Verify install: `opencode-ralph-loop-cli --version`
## Integration Patterns
- Inspect only drifted files: `opencode-ralph-loop-cli check --output json | jq '.files[] | select(.action != "skipped")'`
- Fail CI on any drift: `opencode-ralph-loop-cli check --strict --output quiet`
- Automate in GitHub Actions: add `opencode-ralph-loop-cli check --strict` as a workflow step after checkout
- Use in Makefile: `init: opencode-ralph-loop-cli init --dry-run && opencode-ralph-loop-cli init`
- Force reinit in reset scripts: `opencode-ralph-loop-cli uninstall --force && opencode-ralph-loop-cli init --force`
- Stream NDJSON events to a log aggregator: `opencode-ralph-loop-cli init --output ndjson | tee init.log`
## Performance
- Binary size under 5 MB on all supported platforms (stripped, LTO enabled)
- Startup under 50 ms including SHA-256 integrity checks
- Zero network calls during init, check, list, and uninstall operations
- Atomic file writes prevent partial state on process interruption
## Troubleshooting
### Conflict without --force (exit 3)
- A file in `.opencode/` was modified since the last `init`
- Run `opencode-ralph-loop-cli check` to inspect which files differ
- Use `--force` to overwrite with the canonical template content
### Manifest missing or corrupted (exit 6)
- `.opencode/.manifest.json` is absent or contains invalid JSON
- Run `opencode-ralph-loop-cli init` to regenerate the manifest
- Use `opencode-ralph-loop-cli uninstall --force` to skip the manifest check
### I/O error or permission denied (exit 4)
- The target directory does not exist or lacks write permission
- Create the directory first, then retry
- Verify with `opencode-ralph-loop-cli init --path <DIR> --dry-run`
### doctor reports bun not found
- Install Bun from `bun.sh` and confirm it is in your PATH
- Alternatively use `node` and `npm install` inside `.opencode/`
### JSON output contains unexpected text
- Use `--output json` explicitly and validate with `jq '.'`
- Confirm `--verbose` is NOT set — verbose output goes to stderr only
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, branching strategy, and PR checklist.
## Security
See [SECURITY.md](SECURITY.md) for the vulnerability disclosure policy and response timeline.
## Code of Conduct
See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for the full release history.
## License
- Licensed under MIT OR Apache-2.0 at your option
- See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) for full texts