/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 formatting.

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 provision           # Install missing tools on hosts
rr doctor              # Diagnose issues
rr monitor             # TUI dashboard for host metrics

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]

sync:
  exclude: [.git/, node_modules/, .venv/]

tasks:
  test:
    run: pytest -v

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 <taskname>` | Run named task | | `rr tasks` | List available tasks | | `rr provision` | Install missing tools on hosts | | `rr doctor` | Diagnose issues | | `rr host list/add/remove` | Manage hosts |

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

Common Flags

• `--pretty` / `-p` - Opt into human-readable output (spinners, colors). Default is structured JSON.
• `--host <name>` - Target specific host
• `--tag <tag>` - Select host by tag
• `--local` - Force local execution
• `--skip-requirements` - Skip requirement checks

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`

Extra arguments append to single-command tasks: `rr test -k "test_login"`

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

Task Types and Arguments

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

| Type | Config field | Accepts args? | Example | |------|-------------|---------------|---------| | Single-command | `run:` | YES | `rr test -k "test_foo"` | | Multi-step | `steps:` | NO (errors) | `rr deploy` | | Parallel | `parallel:` | NO unless `forward_args: true` | `rr test-all` |

**When you need custom args on a parallel task, bypass it:**

# Preferred: use --cwd for subdirectory execution (path-traversal safe)
rr run --cwd backend "uv run pytest tests/bond/ -v"

# Fallback: manual cd pattern (avoid — quoting errors are common)
rr run "cd backend && uv run pytest tests/bond/ -v"

To check which type a task is: `rr <task> --help`

To forward args to all subtasks in a parallel task, set `forward_args: true` in the task config:

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

Choosing the Right Command

Need to run something remotely?
├── Named task exists? → rr <task>
│   ├── Single-command task → rr <task> <args>   (args forwarded)
│   ├── Parallel task (forward_args: true) → rr <task> <args>
│   └── Parallel task (default) → rr run "cd <dir> && <cmd> <args>"
├── No task, files may have changed → rr run "<command>"   (syncs first)
└── Files already synced → rr exec "<command>"   (faster, skips sync)

**Never nest rr inside rr exec** — rr may not be installed on the remote:

# Wrong:  rr exec "rr sync && pytest"
# Right:  rr run "pytest"

Reading rr Output

rr sends phase events (connect, sync, exec) to stderr and command output to stdout.

rr test-opendata 2>/dev/null         # suppress all phase events
rr test-opendata --no-phases         # suppress intermediate events, keep final result JSON
rr test-opendata 2>&1                # capture everything (mixes phase JSON into output stream)

The final result is always a JSON line on stderr with `"type":"result"` containing exit code, host, and duration.

Remote Environment Bootstrap

Declare required tools with `require:` - rr verifies they exist before running commands:

# .rr.yaml
require:
  - go
  - node

tasks:
  build:
    run: make build
    require: [cargo]  # Task-specific requirement

# ~/.rr/config.yaml
hosts:
  gpu-box:
    ssh: [gpu.local]
    require: [nvidia-smi, python3]  # Host-specific requirements

Run with: `rr test-all`, `rr quick-check`

Setup Phase (Once Per Host)

Avoid redundant setup work (dependency sync, migrations) when multiple subtasks run on the same host:

tasks:
  test-all:
    setup: pip install -r requirements.txt   # Runs once per host
    parallel:
      - test-unit
      - test-integration
      - test-e2e

Setup runs exactly once per host before any subtasks execute. If a host runs 3 subtasks, setup runs once (not 3 times).

Parallel Task Flags

| Flag | Purpose | |------|---------| | `--stream` | Show real-time interleaved output with `[host:task]` prefixes | | `--verbose` | Show full output per task on completion | | `--quiet` | Summary only | | `--fail-fast` | St