Metadata-Version: 2.4
Name: runbuoy
Version: 0.1.4
Summary: Read-only command status delivery for RunBuoy
Project-URL: Homepage, https://github.com/TANG617/RunBuoy
Project-URL: Documentation, https://github.com/TANG617/RunBuoy#readme
Project-URL: Repository, https://github.com/TANG617/RunBuoy
Project-URL: Issues, https://github.com/TANG617/RunBuoy/issues
License-Expression: MIT
License-File: LICENSE
Keywords: cli,monitoring,notifications,progress,runbuoy
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: qrcode<9,>=7.4
Requires-Dist: rich<15,>=13.7
Requires-Dist: typer<1,>=0.12
Description-Content-Type: text/markdown

# 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:

```bash
# macOS
brew install tmux

# Debian or Ubuntu
sudo apt install tmux
```

## Install

Install the CLI in an isolated environment with
[uv](https://docs.astral.sh/uv/):

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

Or use [pipx](https://pipx.pypa.io/):

```bash
pipx install runbuoy
```

The installed executable is available directly:

```bash
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:

```bash
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:

```bash
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:

```bash
uv tool upgrade runbuoy
# or
pipx upgrade runbuoy
```

## Quick start

Pair this machine with the RunBuoy iOS app:

```bash
runbuoy device pair
```

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

```bash
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:

```bash
runbuoy demo notification
runbuoy demo live-activity
```

Run a command:

```bash
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:

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

Send a notification without starting a managed run:

```bash
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](https://github.com/TANG617/RunBuoy/blob/main/docs/design/security.md)
for the complete data boundary.

## Source and support

Source code, documentation, and issue tracking are available in the
[RunBuoy repository](https://github.com/TANG617/RunBuoy).
Maintainer packaging and release instructions are in
[`docs/developer-guide/cli-distribution.md`](https://github.com/TANG617/RunBuoy/blob/main/docs/developer-guide/cli-distribution.md).

RunBuoy is licensed under the MIT License.
