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 <command> --help for command-specific help, and rivets --version for the installed version.

Commands

Command	What it does
`rivets worker connect`	Connect this machine as a worker and run the daemon in the foreground.
`rivets worker configure`	Save a background-service configuration supplied on stdin.
`rivets worker install`	Install and start a per-user background worker service.
`rivets worker status`	Show background service state and worker health.
`rivets worker restart`	Safely restart an idle background worker service.
`rivets worker logs`	Show a bounded, redacted service log tail.
`rivets worker stop`	Stop an idle background worker service but keep it installed.
`rivets worker uninstall`	Stop and remove the Rivets-managed worker service.
`rivets status`	Show saved config, detected agent CLIs, and repositories and worktrees on disk.
`rivets doctor`	Check prerequisites: git, bun, terminal support, claude, codex, and tailscale (optional).
`rivets update`	Update this standalone worker, or only check for an update.

rivets worker connect

rivets worker connect [--url <url>] [--token-stdin] [--name <name>] [--max-workers <count>] [options]

Connects to Rivets and runs the worker in the foreground. On first run, --token-stdin is required. The token is stored in the OS credential store and reused, so later runs need no flags.

Flag	Default	Description
`--url <url>`	`https://app.rivets.dev`	Rivets URL. You do not need to set this.
`--token-stdin`		Read the one-time worker token from stdin. Interactive input is hidden; piped input is bounded. Recommended.
`--token <token>`		Deprecated. Exposes the token in the process arguments.
`--name <name>`	Hostname	Display name for this worker.
`--max-workers <count>`	Unlimited	Maximum concurrent agent tasks.
`--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. Applies only to an installed background service, and only restarts while idle.
`--scripts` / `--no-scripts`	On	Run repositories’ checked-in `.rivets/settings.toml` scripts.
`--no-save`		Use the supplied options without changing `~/.rivets/config.json`.
`-h`, `--help`		Show help.

rivets worker configure

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

Saves a configuration for the background service without starting the daemon. Reads a JSON object from stdin with url and token (required) and optional booleans directTransport, loopbackTransport, autoUpdate, and projectScripts. See Background service.

Service commands

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

Command	Description
`install`	Install, or safely update, and start the user service. An existing running service must be idle.
`status`	Show service state and worker health.
`restart`	Restart only when there are no active jobs, terminals, or queued events.
`logs`	Print a redacted, bounded log tail.
`stop`	Stop the service when idle and keep it from starting at login. `install` starts it again.
`uninstall`	Stop and remove the managed service when idle. Keeps logs, config, keys, repositories, and worktrees.

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

rivets status

Prints the saved configuration with the token redacted, whether claude and codex are on PATH and their versions, and the repositories and worktrees under ~/.rivets.

rivets doctor

rivets doctor [--yes]

Checks git 2.40 or later, bun, terminal PTY support, the claude and codex CLIs, 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 Windows the replacement completes after the command exits.

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.

Exit status

Commands exit with status 1 when they fail. rivets doctor exits with status 1 when git is missing.

Environment variables

Variable	Description
`RIVETS_HOME`	Worker state directory. Defaults to `~/.rivets`.
`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.

Examples

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

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

Install it as a service and follow its logs:

rivets worker install
rivets worker status
rivets worker logs --lines 200

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

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

Check for an update without installing it:

rivets update --check