opencode-ralph-loop-cli

"One command scaffolds the complete OpenCode Ralph Loop plugin setup."

Read this in Português.

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

• 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

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

Exit Codes

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 for development setup, branching strategy, and PR checklist.

Security

See SECURITY.md for the vulnerability disclosure policy and response timeline.

Code of Conduct

See CODE_OF_CONDUCT.md for community standards.

Changelog

See CHANGELOG.md for the full release history.

License

• Licensed under MIT OR Apache-2.0 at your option
• See LICENSE-MIT and LICENSE-APACHE for full texts