RelayRunner docs: CLI Page: https://relayrunner.app/docs/reference/cli Markdown: https://relayrunner.app/docs/reference/cli.md All pages: https://relayrunner.app/docs/llms.txt Other pages (Markdown): - Changelog: https://relayrunner.app/docs/changelog.md - CLI changelog: https://relayrunner.app/docs/changelog/cli.md - CI traces in your observability tool: https://relayrunner.app/docs/changelog/opentelemetry-traces.md - Platform changelog: https://relayrunner.app/docs/changelog/platform.md - Retries, queueing and provider usage: https://relayrunner.app/docs/changelog/retries-queueing-and-provider-usage.md - Optimized checks: https://relayrunner.app/docs/concepts/optimized-checks.md - Principles: https://relayrunner.app/docs/concepts/principles.md - Routing: https://relayrunner.app/docs/concepts/routing.md - Runner order: https://relayrunner.app/docs/concepts/runner-order.md - Add a provider: https://relayrunner.app/docs/contribute/add-provider.md - Feedback: https://relayrunner.app/docs/contribute/feedback.md - Activity and history: https://relayrunner.app/docs/dashboard/activity.md - Performance: https://relayrunner.app/docs/dashboard/performance.md - Remove RelayRunner: https://relayrunner.app/docs/dashboard/remove.md - Signals: https://relayrunner.app/docs/dashboard/signals.md - Telemetry: https://relayrunner.app/docs/dashboard/telemetry.md - Usage and savings: https://relayrunner.app/docs/dashboard/usage.md - Workspaces and members: https://relayrunner.app/docs/dashboard/workspaces.md - Set up with an agent: https://relayrunner.app/docs/get-started/agents.md - How it works with GitHub Actions: https://relayrunner.app/docs/get-started/github-actions.md - Install the CLI: https://relayrunner.app/docs/get-started/install.md - Move your workflows over: https://relayrunner.app/docs/get-started/move-over.md - Route GitHub Actions jobs to any runner: https://relayrunner.app/docs/get-started/overview.md - Quickstart: https://relayrunner.app/docs/get-started/quickstart.md - Keep up with coding agents: https://relayrunner.app/docs/guides/agent-surge.md - Run CI on your laptop while you work: https://relayrunner.app/docs/guides/laptop-ci.md - macOS and iOS builds on your Mac: https://relayrunner.app/docs/guides/mac-builds.md - Spend controls: https://relayrunner.app/docs/guides/spend-controls.md - Share your team's machines: https://relayrunner.app/docs/guides/team-machines.md - RelayRunner API: https://relayrunner.app/docs/reference/api.md - CLI: https://relayrunner.app/docs/reference/cli.md (this page) - Errors: https://relayrunner.app/docs/reference/errors.md - FAQ: https://relayrunner.app/docs/reference/faq.md - GitHub App: https://relayrunner.app/docs/reference/github-app.md - Runner labels: https://relayrunner.app/docs/reference/labels.md - MCP server: https://relayrunner.app/docs/reference/mcp.md - Data and privacy: https://relayrunner.app/docs/reference/privacy.md - relay.yml inputs: https://relayrunner.app/docs/reference/relay-inputs.md - Repo config: https://relayrunner.app/docs/reference/repo-config.md - Security: https://relayrunner.app/docs/reference/security.md - Troubleshooting: https://relayrunner.app/docs/reference/troubleshooting.md - GitHub-hosted: https://relayrunner.app/docs/runners/github.md - Hosted providers: https://relayrunner.app/docs/runners/hosted.md - Providers: https://relayrunner.app/docs/runners/providers.md - Your machines: https://relayrunner.app/docs/runners/self-hosted.md --- # CLI > Every relayrunner command and flag. The `relayrunner` CLI runs on macOS and Linux with Node.js 22 or newer. Run it with `npx relayrunner `, or install it with `npm install --global relayrunner`. See [Install](/docs/get-started/install). ## `connect` ```sh relayrunner connect ``` Puts this machine online and runs the jobs it's sent until you stop it. On a Mac with Apple silicon and Apple's container tool, each job runs in its own Linux VM; elsewhere jobs run on the machine itself. It runs up to 2 jobs at once on a computer with 8 or more CPU cores, otherwise 1; `--concurrency` changes that. The first run signs the machine in. Ctrl-C takes it offline, and a job that's running stops with it. Press `p` to pause or resume. While it stays open, it checks for a newer GitHub runner every few hours and switches to it between jobs. Run inside a repo with no routed jobs, it offers to route them, the same as `init`. | Flag | What it does | | ------------------------- | ---------------------------------------------------------------------------- | | `--name ` | The machine's name. Defaults to the computer's name. | | `--share only-me\|anyone` | Who can run jobs on this machine. | | `--concurrency ` | How many jobs to run at once. Defaults to 2 with 8+ CPU cores, else 1. | | `--macos` | Also take macOS jobs, which run on the Mac itself. Linux jobs stay in VMs. | | `--cpus ` | CPUs for each job's VM. Defaults to an even share of the Mac's cores. | | `--memory ` | Memory for each job's VM. Defaults to an even share of half the Mac's. | | `--image ` | Your own runner image for the VMs, used with the tools it has. | | `--local-network` | Let jobs in VMs reach your Mac and your local network. | | `--no-isolated` | Run jobs on the Mac itself, where they can read your files. | | `--isolated` | Stop with an error when jobs can't run in VMs, where the default falls back. | The VM flags apply to Macs with Apple silicon. See [Isolated jobs on a Mac](/docs/runners/self-hosted#isolated-jobs-on-a-mac). ## `login` ```sh relayrunner login ``` Signs this machine in and exits, without putting it online. For agents and scripts. Takes `--name` and `--share` like `connect`. ## `whoami` ```sh relayrunner whoami [--json] ``` Shows the machine, the workspaces it's in, who enrolled it, its sharing setting and whether it's online. ## `init` ```sh relayrunner init [--plan] [--apply ] [--json] ``` Routes a repo's jobs through RelayRunner. Run it inside a checkout. See [Move your workflows over](/docs/get-started/move-over). | Flag | What it does | | ---------------- | -------------------------------------------------------------------------------------- | | `--plan` | List the jobs and what would happen. Changes nothing. | | `--apply ` | Route these jobs without prompting: ids (`test`), `file:id` (`ci.yml:test`), or `all`. | | `--json` | Print the result as JSON. | ## `pause` and `resume` ```sh relayrunner pause relayrunner resume ``` Stops new jobs reaching this machine while it stays connected, and lets them through again. A running job finishes. ## `share` ```sh relayrunner share # show the current setting relayrunner share only-me # only jobs you started relayrunner share anyone # any job in the workspace ``` ## `workspaces` ```sh relayrunner workspaces # which workspaces this machine runs jobs in relayrunner workspaces add acme # run jobs from Acme here too relayrunner workspaces remove acme # stop running Acme's jobs here ``` You pick the machine's workspaces when you approve it; this changes them later. `add` and `remove` take a workspace's name, slug or id, or show a list to pick from when you leave it out. Adding a workspace while sharing is `anyone` warns that anyone who can push to its private repos can run jobs on the machine. See the [changelog](/docs/changelog) for what's new. ## `firewall` ```sh relayrunner firewall # show whether it's on relayrunner firewall on # asks for your password relayrunner firewall off ``` Turns on a firewall on your Mac for [isolated jobs](/docs/runners/self-hosted#isolated-jobs-on-a-mac). Job VMs can reach the internet, not your Mac or your local network, and no job can remove it. It stays on after a restart.