CLI

The rivets CLI is the Rivets worker. It connects a machine to your organization, runs agents, and manages its own background service and updates. It does not create tasks or manage your organization; use the apps or the MCP server for that.

rivets <command> [options]

Run rivets --help for the command list, rivets <command> --help for a command’s options, and rivets --version for the installed version.

Install

On macOS and Linux, install or update the CLI with:

curl -fsSL https://app.rivets.dev/install.sh | sh

With a worker token from Add worker, the same script also connects the machine and starts the background worker:

curl -fsSL https://app.rivets.dev/install.sh | RIVETS_TOKEN=rvw_... sh

The script detects the platform (arm64 or x64, glibc or musl), verifies the download’s SHA-256 checksum against the release manifest, installs rivets to ~/.local/bin, and adds that directory to your shell’s startup file if it is not on your PATH. It needs curl or wget, and one of sha256sum, shasum, or openssl.

Variable	Description
`RIVETS_TOKEN`	One-time worker token (`rvw_...`). Connects the machine and starts the background worker.
`RIVETS_WORKER_NAME`	Local name for this worker. Defaults to the hostname.
`RIVETS_INSTALL_DIR`	Where to install `rivets`. Defaults to `~/.local/bin`.
`RIVETS_NO_MODIFY_PATH=1`	Leave shell startup files alone.
`RIVETS_NO_SERVICE=1`	Connect, but skip the background worker. Start it with `rivets run`.

On Windows, install or update it from PowerShell, not as administrator:

irm https://app.rivets.dev/install.ps1 | iex

With $env:RIVETS_TOKEN='rvw_...' set first, it also connects the PC and starts the background worker. It installs rivets.exe to %LOCALAPPDATA%\Programs\Rivets and adds that folder to your user PATH. It takes the same RIVETS_WORKER_NAME, RIVETS_INSTALL_DIR, RIVETS_NO_MODIFY_PATH, and RIVETS_NO_SERVICE variables. You can also download rivets.exe from downloads.frontier.sh/rivets/worker and put it on your PATH yourself. See Connect a worker.

Commands

Command	What it does
`rivets connect`	Connect this machine and run the worker as a background service.
`rivets run`	Run the worker in this terminal.
`rivets status`	Show the connection, background worker, agent CLIs, and repositories on disk.
`rivets logs`	Show recent background worker log lines, redacted.
`rivets restart`	Restart the background worker once it is idle.
`rivets stop`	Stop the background worker once it is idle. It stays installed.
`rivets install`	Reinstall the background worker from the saved connection.
`rivets uninstall`	Remove the background worker once it is idle.
`rivets doctor`	Check git, Claude Code, Codex, and Tailscale.
`rivets update`	Update this standalone worker, or only check for an update.
`rivets configure`	Save a connection supplied on stdin, for provisioning scripts.
`rivets preview`	Show a server from inside a task in the task’s Preview tab.

rivets connect and rivets run

rivets connect [--token-stdin] [options]
rivets run [--token-stdin] [options]

rivets connect saves the connection and installs and starts the background service, so the worker keeps running after you log out and starts again after a restart. If the service is already running, it restarts it with the new settings once the worker is idle.

rivets run saves the connection and runs the worker in the foreground until you stop it. Use it in containers, under tmux, or under your own process supervisor. It is also what the background service runs.

The first time, pass --token-stdin. The token is stored in the OS credential store, and the other options in ~/.rivets/config.json, so later runs need no flags. Run rivets connect again with only the options you want to change, or with --token-stdin to switch to a new token.

Flag	Default	Description
`--token-stdin`		Read the one-time worker token. You are prompted with input hidden, or you can pipe it in. Needed the first time and to switch token.
`--url <url>`	Saved URL, else `https://app.rivets.dev`	Rivets server. You do not need to set this.
`--name <name>`	Saved name, else the hostname	Display name for this worker.
`--max-workers <count>`	Unlimited	Maximum concurrent tasks, from 1 to 32.
`--direct` / `--no-direct`	Off	Send terminal traffic over an existing Tailscale setup.
`--loopback` / `--no-loopback`	On	Keep same-machine terminal traffic on `127.0.0.1`, or send it through the relay.
`--auto-update` / `--no-auto-update`	On	Install signed releases unattended while idle. Applies to the background worker.
`--scripts` / `--no-scripts`	On	Run repositories’ checked-in `.rivets/settings.toml` scripts.
`--no-save`		`rivets run` only. Use the supplied options without changing `~/.rivets/config.json`.
`-h`, `--help`		Show help.

An explicit --url always wins over the saved URL, and a saved URL wins over the default.

rivets status

rivets status [--json]

Prints:

Connection: server, name, the token in redacted form, where the credentials are stored, and whether auto-update and scripts are on.
Background worker: whether the service is supported, configured, installed, enabled, and running; protocol compatibility; health and last heartbeat; active jobs, terminals, and previews; queued events; any delivery stall, degraded reason, or recent crash; and the service label and definition path. On Linux it also says whether the worker keeps running after you log out.
Agent CLIs: whether claude and codex are on PATH, and their versions.
Repos and worktrees on disk under ~/.rivets.

Flag	Description
`--json`	Print only the background worker’s state, as a JSON object.

Background worker commands

rivets install [--force]
rivets restart [--force]
rivets stop [--force]
rivets uninstall [--force]
rivets logs [--lines <n>]

Command	Description
`install`	Install, or refresh, and start the service from the saved connection. A running service is replaced only while idle.
`restart`	Restart only when there are no active jobs, terminals, previews, or queued events.
`stop`	Stop the service when idle and keep it from starting at login. `install` starts it again.
`uninstall`	Stop and remove the service when idle. Keeps the saved connection, logs, keys, repositories, and worktrees.
`logs`	Print the last lines of the service log, with secrets redacted.

Flag	Applies to	Description
`--force`	`install`, `restart`, `stop`, `uninstall`	Override idle protection and interrupt active work.
`--lines <n>`	`logs`	Number of lines. Default 100, maximum 1,000.

Each RIVETS_HOME is its own worker with its own service, so several can run side by side. See Background service.

rivets doctor

rivets doctor [--yes]

Checks git 2.40 or later, bun, terminal PTY support, whether the claude and codex CLIs are installed and signed in, and optionally tailscale. Prints a table of results.

Flag	Description
`--yes`	Allow installing optional tooling. Currently only Tailscale, with `brew install --cask tailscale`, on macOS. Without it, doctor only prints install instructions.

rivets update

rivets update [--check]

Checks for a newer standalone worker release and replaces this executable after verifying its Ed25519 signature, SHA-256 checksum, and embedded version. On macOS and Linux, restart the background worker afterwards with rivets restart. On Windows the replacement completes after the command exits, and a managed background worker is restarted for you.

Flag	Description
`--check`	Report whether an update exists without installing it.

rivets update refuses to overwrite source checkouts, package-manager installs, and the worker bundled in the Mac app. See Updates.

rivets preview

rivets preview [port] [--name <name>] [--path </path>]
rivets preview list
rivets preview remove <port> | --all

Registers a local web server to show in the current task’s Preview tab. Run it inside a task: in its terminal, a script, or by its agent. It refuses to run outside a worktree of this worker.

Argument	Default	Description
`[port]`	`$RIVETS_PORT`	The port to show. Each task has ten of its own, `$RIVETS_PORT` to `$RIVETS_PORT + 9`.
`--name <name>`	`Port <port>`	Label in the Preview tab.
`--path </path>`	`/`	Where the preview opens.
`list`		List this task’s registrations, and whether each one is listening.
`remove <port>`, `remove --all`		Remove one registration, or all of them.

The preview appears once something accepts connections on that port on loopback, and goes away while nothing does. Registering a port again replaces its entry. See Previews.

rivets configure

rivets configure --name <name> [--max-workers <count>] < config.json

Saves a connection without starting the worker. Reads a JSON object from stdin with url and token (required) and optional booleans directTransport, loopbackTransport, autoUpdate, and projectScripts. --name is required, up to 200 characters. Run rivets install afterwards. The one-line installer uses this command. See Background service.

Exit status

Commands exit with status 1 when they fail. rivets doctor exits with status 1 when git is missing. rivets connect exits with status 1 when the machine has no saved connection and no token was given, or when the background service could not start. The connection is still saved in that case, so you can run the worker with rivets run.

Environment variables

Variable	Description
`RIVETS_HOME`	Worker state directory. Defaults to `~/.rivets`. Each directory is a separate worker with its own background service.
`RIVETS_MAX_WORKERS`	Maximum concurrent tasks, used when `--max-workers` is not given. From 1 to 32.
`RIVETS_CLAUDE_MODELS`	Comma-separated Claude model IDs to offer in addition to the built-in list.
`RIVETS_CODEX_MODELS`	Comma-separated Codex model IDs, used when model discovery returns nothing.
`RIVETS_CLAUDE_SESSION_IDLE_MS`	How long an idle Claude process is kept warm. Default 2 hours, minimum 1 second.
`RIVETS_CLAUDE_MAX_IDLE_SESSIONS`	Maximum idle Claude processes kept warm. Default 8, range 1 to 64.
`RIVETS_AGENT_IDLE_TIMEOUT_MS`	How long an agent may go silent, while no tool or background task is running, before its turn is stopped as unresponsive. Default 15 minutes, minimum 30 seconds.
`RIVETS_AGENT_MAX_RUNTIME_MS`	Longest a single agent turn may run before it is stopped. Default 6 hours, minimum 5 minutes.

On macOS and Linux, the background service starts the worker with only RIVETS_HOME and a fixed PATH, so the tuning variables reach a worker you start yourself with rivets run, not the service. RIVETS_MAX_WORKERS is the exception: rivets connect saves it to config.json, like --max-workers.

Examples

Connect a new worker with a custom name and a concurrency cap:

rivets connect --token-stdin --name build-box --max-workers 4

Check it and follow its logs:

rivets status
rivets logs --lines 200

Connect a shared machine that never runs repository scripts and never updates unattended:

rivets connect --token-stdin --no-scripts --no-auto-update

Run a worker in a container, in the foreground:

rivets run --token-stdin < token.txt

Check for an update without installing it:

rivets update --check