# CLI

> Source: `src/content/docs/cli.mdx`
> Canonical URL: https://rivet.dev/docs/cli
> Description: 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:

```bash
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 engine` | Run the bundled `rivet-engine` binary directly. |
| `rivet setup-ci` | Install the GitHub Actions deploy workflow. |

## `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.

```bash
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. See [Deploying to Rivet Compute](/docs/deploy/rivet-compute).

```bash
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. |
| `--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 engine`

Runs the bundled `rivet-engine` binary directly, against the same local database and ports as `rivet dev`. Arguments are forwarded verbatim.

```bash
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:

```bash
gh secret set RIVET_CLOUD_TOKEN
```

## 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.

## Related

- [Deploying to Rivet Compute](/docs/deploy/rivet-compute)
- [Cloudflare Workers Quickstart](/docs/actors/quickstart/cloudflare)
- [Supabase Functions Quickstart](/docs/actors/quickstart/supabase)

_Source doc path: /docs/cli_