RunBuoy CLI

RunBuoy keeps long-running commands visible from an iPhone without exposing a remote-control surface. The CLI runs commands locally, records structured status and progress, and sends a deliberately limited projection to a paired RunBuoy server.

Requirements

• macOS or Linux
• Python 3.12 or newer
• tmux for durable runs

Install tmux before RunBuoy:

# macOS
brew install tmux

# Debian or Ubuntu
sudo apt install tmux

Install

Install the CLI in an isolated environment with uv:

uv tool install --python 3.12 runbuoy
runbuoy completion install zsh  # or bash / fish

Or use pipx:

pipx install runbuoy

The installed executable is available directly:

runbuoy doctor
runbuoy capabilities --json

New installations use the Global region at https://api.runbuoy.cloud by default. Mainland China users should select their hosted region before pairing:

runbuoy config set --region cn

The corresponding endpoint is https://api-cn.runbuoy.cloud. The region and server URL cannot be changed after the Machine is paired. Self-hosted users can instead run runbuoy config set --server-url <url> before pairing.

Set the canonical Machine name from the CLI:

runbuoy config set --machine-name "Build Mac"

When paired, the CLI synchronizes the name to the Server immediately. If the Server is unavailable, the latest name remains queued locally and the next Run uploader retries it. iOS intentionally has no Machine-name editor.

Upgrade with the same tool used for installation:

uv tool upgrade runbuoy
# or
pipx upgrade runbuoy

Quick start

Pair this machine with the RunBuoy iOS app:

runbuoy device pair

To stop delivery from this machine, revoke the Server credential before removing its local copy:

runbuoy device unpair
runbuoy device unpair --yes --json       # automation/non-interactive use
runbuoy device unpair --local-only --yes # emergency local cleanup only

The default command keeps the local credential if Server revocation fails, so it can be retried safely. --local-only warns that the Server credential may still be valid. Neither form deletes the stable machine ID, local Runs, SQLite outbox, or logs.

Verify delivery with built-in examples:

runbuoy demo notification
runbuoy demo live-activity

Run a command:

runbuoy run -- python3 experiment.py

Local execution does not require pairing or Server reachability. Events remain in the local outbox and can be retried later with runbuoy sync --json. The default detached command returns only after the Worker is ready and the target has started; use --wait only when the caller needs the final target exit code.

Use --live-activity immediate when the Live Activity should start as soon as the Run reaches the Server. The default automatic policy filters out Runs that finish within five seconds; disabled suppresses Live Activity start.

runbuoy list shows active Runs. Use runbuoy list -a to include completed history. Run IDs may be supplied as unique prefixes, or as @latest. runbuoy status <run-id> renders a terminal progress and health snapshot; add --watch to keep the display live until the Run reaches a terminal state. Use --json for stable machine-readable output. Preview old local history before permanently pruning it with:

runbuoy history prune --older-than 30d --dry-run

Send a notification without starting a managed run:

runbuoy notify \
  --title "Build completed" \
  --body "Release build succeeded" \
  --level success

RunBuoy does not upload full command arguments, working directories, environment variables, source code, or complete logs by default. See the security documentation for the complete data boundary.

Source and support

Source code, documentation, and issue tracking are available in the RunBuoy repository. Maintainer packaging and release instructions are in docs/developer-guide/cli-distribution.md.

RunBuoy is licensed under the MIT License.