/rr

name: rr
description: Sync code and run commands on remote machines. Use when running tests, builds, or commands remotely, syncing files to hosts, setting up remote development, or troubleshooting rr configuration.
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Edit
  - Grep
  - Glob

rr (Road Runner) CLI

rr syncs code to remote machines and runs commands there. Handles host failover, file sync with rsync, distributed locking, and test output parsing.

Quick Reference

rr run "make test"     # Sync files + run command
rr exec "git status"   # Run command without syncing
rr sync                # Just sync files
rr <taskname>          # Run named task from config
rr tasks               # List tasks
rr provision           # Install missing tools on hosts
rr doctor              # Diagnose issues
rr unlock <host>       # Release a stuck lock
rr monitor --once --json  # One-shot host metrics snapshot

Two-Config System

rr uses two config files:

| Config | Location | Purpose | |--------|----------|---------| | Global | `~/.rr/config.yaml` | Personal host definitions (SSH, directories) | | Project | `.rr.yaml` | Shareable project settings (tasks, sync rules) |

**See [config.md](reference/config.md) for complete config reference.**

Minimal Global Config

version: 1
hosts:
  mini:
    ssh: [mac-mini.local, mac-mini-tailscale]
    dir: ${HOME}/projects/${PROJECT}

Minimal Project Config

version: 1
hosts: [mini]

tasks:
  test:
    run: pytest -v

rr ships default sync excludes (`.git`, `.venv`, `node_modules`, caches, agent dirs like `.claude/`) and applies `.gitignore`. A custom `sync.exclude` list **replaces** the defaults, so copy them in if you set one.

Commands Overview

| Command | Purpose | |---------|---------| | `rr run "cmd"` | Sync files, then run command | | `rr exec "cmd"` | Run command without syncing | | `rr sync` | Just sync files | | `rr pull <pattern>` | Download files from the remote | | `rr <taskname>` | Run named task | | `rr tasks` | List available tasks | | `rr status` | Host connectivity and which remote dir this tree syncs to | | `rr provision` | Install missing tools on hosts | | `rr doctor` | Diagnose issues | | `rr unlock [host]` / `rr unlock --all` | Release stuck locks | | `rr prune` | Remove remote dirs left by deleted git worktrees | | `rr host list/add/remove` | Manage hosts |

**See [commands.md](reference/commands.md) for full command reference.**

Common Flags

• `--host <name>` - Target specific host
• `--tag <tag>` - Select host by tag
• `--local` - Run on this machine: through the `local: true` host (its lock, setup and `require`) if there is one, otherwise directly in your terminal
• `--cwd <dir>` - (`run`/`exec`) Directory to run in, relative to the project root
• `--tail N` - (`run`/`exec`/single-command tasks) Reprint the last N log lines after the result
• `--skip-requirements` - (`run`/`exec` only) Skip requirement checks
• `--no-phases` - Suppress intermediate phase events; the final result event is still emitted
• `--pretty` / `-p` - Human-readable output (spinners, colors). Default is structured JSON.

Run `rr --help` or `rr <command> --help` for complete flag reference.

Tasks

Define reusable commands in `.rr.yaml`:

tasks:
  test:
    description: Run tests
    run: pytest -v

  deploy:
    steps:
      - name: Build
        run: make build
      - name: Deploy
        run: ./deploy.sh

Run with: `rr test`, `rr deploy`

Named tasks always run from the project root, regardless of which subdirectory you invoke them from.

**See [tasks.md](reference/tasks.md) for parallel tasks, multi-step tasks, and dependencies.**

Passing Arguments to Tasks

Tasks come in three types. The type determines whether extra args work:

| Type | Config field | Accepts args? | Example | |------|-------------|---------------|---------| | Single-command | `run:` | Yes | `rr test tests/test_api.py` | | Multi-step | `steps:` | No (errors) | `rr deploy` | | Parallel | `parallel:` | Only with `forward_args: true` | `rr test-all` |

Rules for single-command tasks:

• **Flag-like args need `--`.** rr parses flags before the task sees them, so `rr test -k foo` fails with "rr parses flags before the task sees them". Use `rr test -- -k foo`. Positional args (`rr test tests/foo.py`) work without it.
• **Args are shell-quoted.** `rr test -- -k "foo or bar"` arrives as one argument. Remote globs and `$VARS` in args are not expanded; put those in the task's `run` string.
• **Args are appended to the end** of the command, unless the command has an `{args}` placeholder. `{args:-default}` supplies a default when no args are given; `{{args}}` is a literal `{args}`.
• **Compound commands need a placeholder.** If `run` contains pipes, `&&`, `;`, redirections, `$()`, or backticks, passing args without an `{args}` placeholder is an error (otherwise the args would land on the last command in the pipeline).

tasks:
  test:
    run: pytest {args:-tests/} -n 4 | tail -20   # rr test -- -k bond  =>  pytest -k bond -n 4 | tail -20

Parallel tasks reject args, flags included, unless `forward_args: true` is set (`CONFIG_INVALID`, with a hint to set it and use `--`). With it, args are forwarded to every subtask (appended, or substituted into each subtask's `{args}`). Subtasks that are compound commands need an `{args}` placeholder, and multi-step subtasks can't take forwarded args. A forwarded test filter can leave some subtasks with zero matching tests (pytest exits 5).

tasks:
  test-backend:
    parallel: [test-backend-api, test-backend-services]
    forward_args: true   # rr test-backend -- -k bond

**When a parallel task doesn't forward args, bypass it:**

rr run --cwd backend "uv run pytest tests/bond/ -v"

To check a task's type, subtasks, and flags: `rr <task> --help`. This is faster than reading `.rr.yaml`.

Choosing the Right Command

Need to run somet