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>
| Command | Description |
|---|---|
rivet login | Sign in to Rivet Cloud in the browser. |
rivet link | Link the current directory to a project or cluster. |
rivet deploy | Build and deploy the project to Rivet Cloud. |
rivet logs | Read or follow a project’s compute logs. |
rivet pool | List or delete compute pools in a namespace. |
rivet cluster logs | Read or follow a cluster’s engine and runner logs. |
rivet api | Make an authenticated request to the Rivet Cloud API. |
rivet engine | Run the bundled rivet-engine binary directly. |
rivet setup-ci | Install the GitHub Actions deploy workflow. |
rivet token | Mint a namespace-scoped token. |
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.
| Flag | Default | Description |
|---|---|---|
--token | env / credentials | Rivet Cloud API token. |
--namespace | production | Cloud namespace. |
--pool | default | Compute pool to deploy to. |
--project / --org | from token | Override project/org. |
--dockerfile | Dockerfile | Dockerfile to build. |
--build-context | . | Docker build context. |
--env KEY=VAL | — | Environment override, repeatable. |
--image | project slug | Image repository name. |
--tag | git short SHA | Image tag. |
--yes | — | Skip prompts. |
--reuse-image | — | Keep the pool’s current image and skip the Docker build and push. Use it to change resources without a rebuild. |
The pool’s resources and scaling are set with these flags. Each one left out keeps its server-side default.
| Flag | Server default | Description |
|---|---|---|
--cpu | 1 | vCPUs per actor: 1, 2, 4, 8, or a value from 0.08 to below 1 with at most two decimals. |
--memory | 512Mi | Memory per actor, from 512Mi to 4Gi. |
--min-scale | 0 | Actors kept running, 0 to 100. |
--max-scale | 1 | Most actors to scale to, 1 to 5000. |
--max-concurrent-actors | 1000 | Most actors the pool runs at once, 1 to 50000. |
--instance-request-concurrency | 80 | Concurrent requests per actor instance, 1 to 500. |
--drain-grace-period | 1800 | Seconds a draining instance waits for its actors to finish, 5 to 3200. |
--drain-on-version-upgrade | true | Drain instances on the old version when a new one deploys. Pass --drain-on-version-upgrade=false to disable. |
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>
| Flag | Default | Description |
|---|---|---|
--cluster | RIVET_CLUSTER / linked cluster | Cluster to deploy to instead of a project. |
--org | RIVET_ORG / linked organization | Organization the cluster belongs to. |
--region | the cluster’s only region | Region of the pool. Required when the cluster has several regions. |
--pool | default | Pool to roll out. |
--build | new build | Roll out an existing build instead of building a new one. |
--dockerfile | Dockerfile | Dockerfile to build. |
--build-context | . | Docker build context. |
--image | cluster name | Image name recorded on the build. |
--tag | git short SHA | Image tag recorded on the build. |
The saved image must be 5 GiB or smaller. --namespace, --env, --reuse-image, and the resource and scaling flags apply to projects only and are rejected for a cluster. 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[]'
| Flag | Description |
|---|---|
-X, --method | HTTP method. Defaults to GET, or POST with a body. |
-f, --raw-field key=value | String field, repeatable. key[]=value appends to an array and a bare key[] sends an empty array. |
-F, --field key=value | Typed field, repeatable. true, false, null, and numbers become JSON values. @file reads the value from a file. |
--input <file> | JSON file to send as the body, or - for stdin. |
-H, --header 'Name: value' | Extra request header, repeatable. |
-i, --include | Print the response status and headers before the body. |
--token, --cloud-api | Same as rivet deploy. |
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
| Flag | Default | Description |
|---|---|---|
--namespace | production | Cloud namespace. |
--pool | default | Compute pool. |
--region | all | Regions to include, comma-separated. |
--contains | — | Only lines containing this text, case-insensitive. |
-n, --limit | 100 | Number of history lines. Ignored with --follow. |
-f, --follow | — | Keep printing new lines as they arrive. |
--before | — | Page back: only lines before this ISO 8601 timestamp. |
--json | — | Emit JSON lines instead of formatted output. |
--token, --project, --org | — | See Signing in and linking. |
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.
| Flag | Default | Description |
|---|---|---|
--token | env / credentials | Rivet Cloud API token. |
--namespace | production | Cloud namespace. |
--project / --org | from token | Override project/org. |
--json | — | Emit raw JSON instead of formatted output. |
--with-env-vars | — | Include environment variable values, which are secret and omitted otherwise. |
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
| Flag | Default | Description |
|---|---|---|
--namespace | production | Cloud namespace the pool belongs to. |
--yes | — | Skip the confirmation prompt. |
--token | env / credentials | Rivet Cloud API token. |
--project / --org | from token | Override project/org. |
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.
| Flag | Default | Description |
|---|---|---|
--cluster | RIVET_CLUSTER / linked cluster | Cluster to read. Required. |
--source | both | engine or runner. |
--pool | all pools | Only this runner pool’s logs. Cannot be combined with --source engine. |
--severity | all | Only lines at this severity or above: trace, debug, info, warn, error, or fatal. |
--contains | — | Only lines containing this text, case-insensitive. |
-n, --limit | 100 | Number of recent lines to print first, up to 1000. |
-f, --follow | — | Keep printing new lines as they arrive. |
--before | — | Page back: only lines older than this line id from --json output. |
--json | — | Emit JSON lines instead of formatted output. |
--token, --org, --cloud-api | — | Same as rivet deploy. |
Lines can arrive up to a minute late, and --follow prints them when they do.
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
--kind | Prefix | Use |
|---|---|---|
secret | sk_ | Server-side runner/runtime token. |
public | pk_ | Client token: resolve and manage actors. |
connection | ck_ | Client token limited to resolving actors and opening connections. |
By default the namespace must already exist. Pass --create-namespace to create it first (useful for per-branch CI namespaces).
| Flag | Default | Description |
|---|---|---|
--kind | (required) | Token kind: secret, public, or connection. |
--namespace | production | Cloud namespace. |
--create-namespace | — | Create the namespace if it does not exist. |
--token | env / credentials | Rivet Cloud API token. |
--project / --org | from token | Override project/org. |
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.