Command line tool to install RoadRunner binaries and generate configs

This package provides the rr console command for PHP projects that run on RoadRunner: it downloads the RoadRunner server binary and protoc-gen-php-grpc plugin built for your environment and generates a starter .rr.yaml configuration.

Note

Version 3.x of roadrunner/cli targets RoadRunner v3: rr get downloads RoadRunner 3 by default. For RoadRunner 2025.x, use spiral/roadrunner-cli 2.x.

Get Started

Installation

composer require roadrunner/cli

Getting the RoadRunner binary

Download the latest RoadRunner binary for your operating system and architecture into the project root, along with an example .rr.yaml:

vendor/bin/rr get-binary

Then start the server:

./rr serve

See the RoadRunner documentation for the configuration reference.

Commands

• get-binary (or get) - allows to install the latest version of the RoadRunner compatible with your environment (operating system, processor architecture, runtime, etc...). Also, this command creates an example .rr.yaml configuration file. If the command is used without the plugin and preset options, a configuration with the default plugins (rpc, server, http, jobs, kv, metrics) is created. Using the plugin option (shortcut p) can create an example configuration file with only plugins needed. For example, with http plugin only: get-binary -p http, http and jobs: get-binary -p http -p jobs. Available plugins: amqp, beanstalk, boltdb, centrifuge, endure, fileserver, google_pub_sub, grpc, http, jobs, kafka, kv, logs, metrics, nats, nsq, otel, protoreg, redis, rpc, server, service, sqs, status, temporal. Using the preset option can create an example configuration file with popular plugins for different typical tasks. For example, with web preset: get-binary --preset web. Available presets: web (contains plugins http, jobs). Use --no-config to skip the configuration file.
• make-config - creates the .rr.yaml configuration file without downloading the binary. Accepts the same plugin and preset options.
• download-protoc-binary - allows to install the latest version of the protoc-gen-php-grpc file compatible with your environment (operating system, processor architecture, runtime, etc...).
• versions - displays a list of available RoadRunner binary versions.

Common options

The binary commands accept --filter (-f, version constraint; for get-binary and download-protoc-binary * means >=3.0 <2000 and any other || alternative without an upper bound gets <2000, so the calendar releases have to be named explicitly, e.g. 2025.* or >=2025), --stability (-s), --os (-o), --arch (-a) and --location (-l, target directory) options. get-binary and download-protoc-binary download the binaries with DLoad; a project's dload.xml does not affect them.

On a musl host such as Alpine they install the musl build of Linux on their own, even with --os=linux; --os=unknown-musl forces the musl build from any host.

DLoad comes with its own vendor/bin/dload and keeps a version registry in the user cache: ~/.cache/dload, $XDG_CACHE_HOME/dload when that is set, %LOCALAPPDATA%\dload\cache on Windows. DLOAD_CACHE_DIR moves it, DLOAD_CACHE_TTL=0 turns it off.

Releases are fetched from the GitHub API at RR_GITHUB_API_URL, https://api.github.com by default. For get-binary and download-protoc-binary it is either https://api.github.com or a GitHub Enterprise Server API URL ending with /api/v3 (e.g. https://ghe.example.com/api/v3); versions also accepts a mirror.

All commands pick the API token the same way, to avoid the rate limits:

• the public GitHub gets DLOAD_TOKEN_GITHUB_COM, or GITHUB_TOKEN when that one is not set;
• any other server gets only its own DLOAD_TOKEN_<HOST>: the host upper-cased, . as _, - as __, a non-default port after ___ (e.g. DLOAD_TOKEN_GHE_EXAMPLE_COM, DLOAD_TOKEN_GHE_EXAMPLE_COM___8443); GITHUB_TOKEN never leaves the public GitHub;
• over plain http a token is sent only to a loopback host, and it is never carried over a redirect to another host.