CLI

Use the optional Rivet CLI to deploy Rivet Actors to Rivet Cloud and manage Rivet Cloud projects and clusters.

The rivet CLI (@rivetkit/cli) is optional. You only need it to deploy to Rivet Cloud with rivet deploy and to manage Rivet Cloud projects and clusters.

Run it with your package runner:

npx @rivetkit/cli <command>

Signing in and linking

rivet login opens a browser to sign in and stores the session in ~/.rivet/credentials, refreshing it as needed. Pass --no-browser to print the sign-in URL instead. rivet logout removes the session and rivet whoami shows the signed-in account and linked project.

rivet login
rivet link                                  # pick an organization and project
rivet link --org my-org --cluster my-cluster

rivet link writes .rivet/project.json in the current directory, so later commands there default to that project or cluster. It prompts for anything not passed as a flag. rivet unlink removes the link.

Every command that talks to Rivet Cloud resolves its token in this order: --token, RIVET_CLOUD_TOKEN, the rivet login session, then a token saved by an earlier rivet deploy --token. Use --token or RIVET_CLOUD_TOKEN in CI. The project comes from --project and --org (or RIVET_PROJECT and RIVET_ORG). Otherwise an API token names its own project, and a rivet login session uses the linked directory or prompts for one. --cluster (or RIVET_CLUSTER) selects a cluster instead, with --org naming the organization it belongs to. --cloud-api points at a different Cloud API endpoint.

rivet deploy

Builds and pushes your project’s Docker image and upserts the managed pool, printing the dashboard URL. Deploys target the default pool unless you pass --pool; a new pool is created on first deploy. See Deploying to Rivet Cloud.

rivet deploy

A token passed with --token is saved to ~/.rivet/credentials, so later deploys can omit it.

The pool’s resources and scaling are set with these flags. Each one left out keeps its server-side default.

Deploying to a cluster

Pass --cluster to deploy to a cluster instead of a project. The CLI builds the image, uploads it as a build, rolls the pool out to that build, and prints the build ID.

rivet deploy --cluster my-cluster --org my-org

To avoid passing --cluster every time, link the directory once with rivet link --cluster my-cluster or set RIVET_CLUSTER.

Roll back by deploying an earlier build ID. This skips the Docker build and upload.

rivet deploy --cluster my-cluster --build <build-id>

The saved image must be 5 GiB or smaller. --namespace, --reuse-image, and the resource and scaling flags apply to projects only and are rejected for a cluster. --env and --secret keep the pool’s other variables, apply in the same rollout as the build, and are checked before the build starts. They also unpin any secret a rollback pinned. See rivet cluster env. rivet pool, rivet logs, and rivet token do not support clusters. Read a cluster’s logs with rivet cluster logs.

rivet api

Sends a request to any Rivet Cloud API endpoint with your credentials and prints the response body. Use it for endpoints the CLI has no command for.

rivet api /v2/clusters
rivet api '/v2/clusters/{cluster}/builds'
rivet api '/v2/clusters/{cluster}/builds/<build-id>' -X DELETE

The path is sent as written, so /v2/... paths reach API v2 and unprefixed paths reach API v1. Each API serves its OpenAPI spec, which lists every endpoint: rivet api /v2/openapi.json for API v2 and rivet api /doc for API v1. {cluster}, {org}, and {project} are filled from the matching flag or the linked directory.

Fields become a JSON body, and the method defaults to POST when a body is given. With -X GET, fields are sent as query parameters.

rivet api '/v2/clusters/{cluster}/regions/us-east4/runner-pools/default' -X PUT \
  -f build_id=<build-id> -f 'cidr_allowlist[]'

The command exits with a non-zero status when the API responds with an error, after printing the response body.

rivet logs

Prints a project’s compute logs for one pool, oldest first. -f follows new lines live. For a cluster, use rivet cluster logs.

rivet logs
rivet logs --pool workers --contains error -n 200
rivet logs --region us-east4 -f

rivet pool

Manages the compute pools in a namespace. A namespace can hold multiple pools; default is the one used when a deploy or logs command omits --pool.

rivet pool list

rivet pool list

Each pool is printed as a status line (colorized by status) followed by its config (display name, image, resources, environment) and any error. Colors are disabled when stdout is not a terminal or NO_COLOR is set. This human-readable format is not stable; pass --json for machine-readable output.

rivet pool delete

Tears down a compute pool, then waits until it is fully removed, printing status changes as it goes. Prompts for confirmation unless --yes is passed, and refuses to run without confirmation when stdin is not a terminal.

rivet pool delete <name> --yes

rivet cluster logs

Prints a cluster’s most recent engine and runner logs, oldest first. -f keeps following new lines. Use rivet logs for a project’s logs instead.

rivet cluster logs --cluster my-cluster
rivet cluster logs --cluster my-cluster --severity error -n 50
rivet cluster logs --cluster my-cluster --source runner --pool default --contains timeout -f

Each line shows its timestamp, severity, source (engine, or runner/<pool>), and message. This format is not stable; pass --json to print one JSON object per line with id, timestamp, severity, message, source, runner_pool, and instance_id.

Lines can arrive up to a minute late, and --follow prints them when they do.

rivet cluster env

Lists and changes a pool’s environment variables. A variable holds a plain value or the name of a cluster secret. Changes keep the pool’s other variables and roll the pool. Run rivet deploy first so the pool has a build. Put credentials in secrets, since list prints plain values.

rivet cluster env set --env LOG_LEVEL=debug --secret DATABASE_URL

Names are letters, digits, and _, not starting with a digit. Values are one line. A pool holds up to 256 variables. A --secret must already exist, so roll it out first. set and unset unpin any secret a rollback pinned. To set variables with a new build, pass --env and --secret to rivet deploy --cluster.

rivet cluster secret

Manages a cluster’s secrets, which are encrypted values that pool variables reference by name. No command prints a secret’s value.

rivet cluster secret rollout DATABASE_URL

rollout and delete show what will change and ask to confirm. --yes skips this and is required without a terminal, such as in CI.

rollout never takes the value as an argument, where it would land in shell history. It prompts for the value without echoing it, reads stdin when piped, or reads the variable --from-env names. Values must be one line and at most 1 KiB, so base64-encode multi-line values such as PEM keys. Empty values are refused unless you pass --allow-empty.

Secret names are letters, digits, _, and -, up to 64 characters. A cluster holds up to 64 secrets. A cluster token needs rivet:cluster:secrets:write and rivet:cluster:read to manage secrets, plus rivet:cluster:deploy to change a pool’s variables.

rivet engine

Runs the bundled rivet-engine binary directly. Arguments are forwarded verbatim.

rivet engine nuke      # wipe local engine state
rivet engine wf list   # inspect workflows

rivet setup-ci

Installs .github/workflows/rivet-deploy.yml, which deploys to Rivet Cloud on push and pull request. Add --force to overwrite. Then set the token secret:

gh secret set RIVET_CLOUD_TOKEN

rivet token

Mints a namespace-scoped token for connecting to Rivet. Only the token is printed to stdout, so it can be captured directly by scripts (e.g. TOKEN=$(rivet token create --kind secret)).

rivet token create --kind secret

By default the namespace must already exist. Pass --create-namespace to create it first (useful for per-branch CI namespaces).

Engine binary resolution

rivet engine resolves the rivet-engine binary from, in order: --engine-binary, RIVET_ENGINE_BINARY_PATH, a binary bundled next to the CLI, a local target/{debug,release} build, then an auto-downloaded release. Set RIVETKIT_ENGINE_AUTO_DOWNLOAD=0 to require a local binary.

Related

• Deploying to Rivet Cloud