Roadrunner Cli Laravel Package

Getting Started

Install the CLI per project (or globally) with Composer: composer require --dev spiral/roadrunner-cli:^3.0. Version 3.x requires PHP 8.2+ and symfony/console / symfony/http-client 6.4+, and it targets RoadRunner v3 — check both before upgrading an existing project. After installation, run rr list to see available commands. The first use case is unchanged: rr init scaffolds a .rr.yaml and downloads a matching binary. In 3.0.0 the generated config is now guaranteed to be one that RoadRunner 3 accepts (new nsq, kafka, google_pub_sub, centrifuge and protoreg sections are supported), so rr init → rr serve is the fastest path to a working dev server on a fresh project.

Implementation Patterns

• Development Workflow: Use rr serve in the foreground during local development, and pair it with worker commands for queues/events. Generation of a broken config now fails loudly instead of writing .rr.yaml, so a bad rr init won't leave a half-valid file behind.
• CI/CD Automation: Keep rr download, rr version and rr check in pre-deploy scripts, and use rr stop / rr start for scripted restarts instead of kill/nohup. Binary fetching now goes through DLoad, so pin the RR 3.x line explicitly in CI (see gotchas on version filters and tokens).
• Multi-Config Management: Maintain environment-specific files (.rr.local.yaml, .rr.prod.yaml) and select them with rr serve -c .rr.local.yaml. The automatic fallback to rr.yaml, .rr.yaml or config/.rr.yaml still applies when -c is omitted.
• Version Pinning: Use explicit version constraints when downloading binaries. The wildcard filter now resolves to RoadRunner 3.0 or newer, which is convenient for new projects but will silently move you off RR 2.x on existing ones.
• Health Checks & Diagnostics: Keep rr status and rr diagnostics in monitoring/troubleshooting scripts to verify server state and worker failures.

Gotchas and Tips

• RoadRunner 3 only: 3.x of the CLI generates RR3-shaped configs and keeps version filters on the RR 3.x line. Do not mix it with RR 2.x binaries or existing RR 2.x configs. If you are mid-migration, pin the CLI to ^2.7 until the runtime is upgraded.
• Removed plugins: The tcp, websockets, broadcast and reload plugins are gone because RoadRunner 3 no longer ships them. Any .rr.yaml sections referencing them must be removed or replaced before rr serve will work — this is the most likely silent breakage on upgrade.
• Internals are off-limits: Command, Configuration, Downloader and Environment namespaces moved under Internal\*. The abstract Command, OptionInterface, Environment\Enum and the Environment\*Factory classes are removed, and commands plus Configuration\Generator are final. Any custom command, config generator or downloader built on the old public API will break — extend Symfony commands directly instead of subclassing rr commands.
• Repository/Archive API removed: The Archive and Repository namespaces (including Version1\StaticRepository), Command::getRepository(), Command::confirm(), VersionFilterOption::find() and VersionFilterOption::choices() are gone. VersionsCommand is final. Scripts that scraped versions through these APIs need to shell out to rr commands instead.
• Download tokens changed: For get-binary and download-protoc-binary, RR_GITHUB_API_URL must be exactly https://api.github.com or end with /api/v3. GitHub Enterprise Server tokens are no longer read from GITHUB_TOKEN; use DLOAD_TOKEN_<HOST> (e.g. DLOAD_TOKEN_GHE_EXAMPLE_COM). Air-gapped/CI pipelines with the old variable will 401.
• Binary caching: Binaries still land in ~/.rr/bin/ by default. On restricted networks use rr download -o ./bin/rr to stage locally. Note DLoad has documented side effects during downloads — read the docs notes before disabling network access entirely.
• Config precedence: CLI flags (-c, -o, -w) override config at runtime but never modify the file. Use rr init -c .rr.prod.yaml to bootstrap a config, not rr serve -c ... for ad hoc tweaks.
• Worker restart behavior: rr serve -w watches files but ignores vendor/ and hidden files unless overridden via the watch config or --watch with comma-separated paths.
• Permissions: If rr serve fails silently on Unix, check that the binary is executable (chmod +x ~/.rr/bin/rr-*) and that PHP CLI has network access for the initial download.
• Extensibility: With everything moved to Internal and commands marked final, the CLI is no longer a subclassing surface. Integrate by invoking rr from Composer scripts, Makefiles or CI steps rather than extending it in PHP.