CLI
Reference for the optional rivet CLI: deploy to Rivet Compute and run local dev for serverless platforms.
The rivet CLI (@rivetkit/cli) is optional. You only need it for:
| Use case | Command |
|---|---|
| Deploy to Rivet Compute | rivet deploy |
| Local dev for serverless platforms (Cloudflare, Supabase) | rivet dev --provider <name> |
Run it with your package runner:
npx @rivetkit/cli <command>
| Command | Description |
|---|---|
rivet dev | Run a local engine and your handler’s dev server. |
rivet deploy | Build and deploy the project to Rivet Cloud. |
rivet pool | List or delete compute pools in a namespace. |
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. |
rivet dev
Starts a local engine, spawns your dev server, and registers the serverless runner pointing at it. The engine keeps running across restarts; Ctrl-C stops only the dev server.
rivet dev [--provider <serverless|cloudflare|supabase|none>] [--port N] [--fn-name NAME] [--url URL] [-- <command>...]
--provider selects how the dev server is launched. Anything after -- is appended to the preset command (or is the command to run when no provider is set).
--provider | Spawns | Port |
|---|---|---|
| (omitted) | your -- <command> (needs --port) | from --port |
serverless | your -- <command> (gets PORT) | auto |
cloudflare | wrangler dev | 8787 |
supabase | supabase functions serve | 54321 |
none | nothing (engine only) | — |
For cloudflare, the CLI also passes the engine endpoint as --var RIVET_ENDPOINT:..., so the Worker connects back with no wrangler.toml config.
| Flag | Description |
|---|---|
--port | Handler port. Required without a provider unless --url is set. |
--fn-name | Supabase function name (default rivet). |
--url | Explicit handler URL, overriding port and path. |
--engine-binary | Path to a rivet-engine binary. |
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 Compute.
rivet deploy --token cloud_api_xxxxx
The token is saved to ~/.rivet/credentials (also read from RIVET_CLOUD_TOKEN), 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. |
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. |
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 engine
Runs the bundled rivet-engine binary directly, against the same local database and ports as rivet dev. 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 dev and rivet engine resolve 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.