Skip to content

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 <command>, or install it with npm install --global relayrunner. See Install. On a Mac, RelayRunner for Mac runs connect for you from the menu bar.

Terminal window
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 <name> The machine’s name. Defaults to the computer’s name.
--share only-me|anyone Who can run jobs on this machine.
--concurrency <n> 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 <n> CPUs for each job’s VM. Defaults to an even share of the Mac’s cores.
--memory <gb> Memory for each job’s VM. Defaults to an even share of half the Mac’s.
--image <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.
--events For apps that run connect. See Events.

The VM flags apply to Macs with Apple silicon. See Isolated jobs on a Mac.

Only one connect runs on a computer at a time. A second one stops and says so.

With --events, connect writes one JSON object per line to stdout and nothing else; what it would print for you goes to stderr. Send pause or resume on stdin, one per line. To go offline as Ctrl-C does, start it in its own process group and send that group SIGINT. Closing stdin also takes it offline.

{
"v": 1,
"at": "2026-11-16T18:00:00.000Z",
"type": "state",
"link": "online",
"paused": false,
"jobs": [],
"waiting": 1,
"queue": [{ "repo": "acme/app", "since": 1763481600000 }],
"spilled": [],
"slots": 2
}

Types: sign-in (the page and code to approve), machine, state, job-repo, job-result, job-end (the job’s line in history), offline, error, and the connection’s own: connecting, connected, disconnected, run, job, paused, waiting. waiting (also in state) is how many jobs are queued for a slot on this machine: jobs it could run whose machines are all busy. queue lists the longest-waiting of them (repo, since when in ms, and the job’s name and workflow once GitHub has said which job it is), and spilled holds when jobs in the last hour went to another runner because every slot was busy. state also has slots, how many jobs it runs at once. A run event carries job when the gateway knows which job it is: its name, workflow, repo, GitHub link and typicalMs, how long it usually takes on this machine.

Terminal window
relayrunner login

Signs this machine in and exits, without putting it online. For agents and scripts. Takes --name and --share like connect.

Terminal window
relayrunner whoami [--json]

Shows the machine, the workspaces it’s in, who enrolled it, its sharing setting and whether it’s online.

Terminal window
relayrunner init [--plan] [--apply <jobs>] [--auto] [--allow-deploy <jobs>] [--json]

Routes a repo’s jobs through RelayRunner. Run it inside a checkout. See Move your workflows over.

Flag What it does
--plan List the jobs and what would happen. Changes nothing.
--apply <jobs> Route these jobs without prompting: ids (test), file:id (ci.yml:test), or all.
--auto Write auto instead of the label for Linux x64 jobs, so you set their size on the Router page.
--allow-deploy <jobs> Route these jobs even though they look like deploy jobs. The machine gets their secrets and cloud access.
--json Print the result as JSON.
Terminal window
relayrunner pause
relayrunner resume

Stops new jobs reaching this machine while it stays connected, and lets them through again. A running job finishes.

Terminal window
relayrunner share # show the current setting
relayrunner share only-me # only jobs you started
relayrunner share anyone # any job in the workspace
Terminal window
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 for what’s new.

Terminal window
relayrunner history # the last 20 jobs this machine ran
relayrunner history --limit 50
relayrunner history --json

Lists the jobs connect ran on this machine, newest first, with each one’s result and how long it took. They’re kept in ~/.relayrunner/history.jsonl, the newest 500 at least, which the Mac app reads too.

Terminal window
relayrunner blacksmith connect
relayrunner blacksmith connect --workspace acme # when you run more than one workspace

Connects your Blacksmith organization so Settings › Providers shows its real usage: billable minutes and cost per day, and each job’s billable minutes. Blacksmith has no usage API, so RelayRunner reads it with Blacksmith’s own CLI and an org token.

The command runs blacksmith org-token create, which opens your browser for you to approve as an admin of the Blacksmith organization. It sends only the token it prints to RelayRunner, encrypted at rest, and never signs in to Blacksmith or reads Blacksmith’s saved credentials. If Blacksmith’s CLI isn’t installed, it offers to download it into ~/.relayrunner/bin (--yes skips the question), checked against the SHA-256 Blacksmith publishes.

In the browser, approve it for the GitHub organization your workspace is on. A token for any other organization is refused. The token goes to the workspace on that organization, or the one you name when you have more than one. You must own or administer it. Remove the connection in Settings › Providers, then revoke the token with blacksmith org-token revoke <id>. Run relayrunner login first if this computer isn’t signed in.

Terminal window
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. 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.