---
name: rebase-cloud
description: Guide for deploying and operating a project on Rebase Cloud — creating a project, attaching a managed or bring-your-own database, environment variables, extensions, domains, logs and rollbacks — and for connecting Claude to every Rebase project, Cloud or self-hosted, through the Rebase connector (`rebase cloud connect`). Use this when the user wants to ship to Rebase Cloud, is debugging a cloud deployment, or wants Claude connected to their projects. For self-hosting, Docker or Kubernetes, use rebase-deployment instead.
---

# Rebase Cloud

Rebase Cloud is the hosted control plane at [app.rebase.pro](https://app.rebase.pro).
It runs your project as one container per app on Kubernetes, serves it at
`https://<subdomain>.rebase.website`, and gives it a managed PostgreSQL database.

<!-- docs-verify: ignore -->
Everything here is driven by `rebase cloud <command>`. There is no bare
`rebase deploy` or `rebase login` — every cloud command lives under the `cloud`
namespace, and a mistyped one exits 1.

> **⛔ AGENT RULE — read this first.** Never run `rebase cloud deploy`,
> `rebase cloud projects create`, `rebase cloud projects delete`,
> `rebase cloud rollback`, `rebase cloud stop` or any other command that changes
> the hosted platform unless the user asked for it **in the current
> conversation**. Everything in this skill is safe to *read*
> (`status`, `logs`, `deployments`, `env list`, `debug`); the rest is the user's
> call. When in doubt, print the command for them to run.

---

## The first deploy, in order

```bash
rebase cloud login
rebase cloud billing setup     # once per organization
rebase cloud projects create --name "My App" --subdomain my-app --link --yes   # creates billable resources: it asks first, --yes answers
rebase cloud deploy
```

`billing setup` attaches a card to the organization, once. Without one the
control plane answers a deploy with 402, so `deploy` refuses before it builds
(`code: payment_required`).

`projects create` attaches a **managed database** in the same call. That is the
step that used to be missing, and its absence is the single most expensive trap
on this platform — see the next section.

Already have a project, or created one in the console?

```bash
rebase cloud link --project my-app     # link this directory
rebase cloud status                    # what is this project waiting for?
```

### If you passed `--db none`, or the project predates this behaviour

```bash
rebase cloud db create --type managed
rebase cloud deploy
```

### What the deployed URL actually serves

One container per app. The backend container handles:

- **`/api/*`** — the data API, auth, realtime, storage
- **everything else** — your built frontend as a static SPA (via `serveSPA()`)

The admin panel is part of a frontend, not a service of its own, so where it
appears depends on what your frontend is — and on whether `rebase.json` gives
the app that holds it a hostname of its own:

| Project type | What the root URL shows | Where the admin is |
|---|---|---|
| Default scaffold (`rebase init`) | The admin panel itself (login) | `/` — the frontend **is** the admin |
| Custom product frontend | Your product app | Wherever you mount it — commonly `/admin` |
| Admin as its own app with `"path": "https://admin.example.com"` | Your product app | `https://admin.example.com/`, once its DNS verifies — see [Multi-app projects](#multi-app-projects) |
| Backend-only (`rebase init --headless`) | Nothing (API only) | Not deployed |

The `cms` field of the app in `rebase.json` is what the console's *Open CMS*
link points at; on an app with a hostname it is a path on that hostname.

> **IMPORTANT FOR AGENTS:** Every Cloud project runs with `NODE_ENV=production`,
> where the first account to register is **not** promoted to admin. A Cloud
> project needs no admin set up for that: its owners and admins (the owning
> organization's `owner` and `admin` roles) open the admin panel from the
> project's page in the console — **Open CMS**, or the admin's own
> **Continue with Rebase Cloud** — and are signed in as `admin`, the account
> created on first use. Send the user there; do not ask them for
> `REBASE_ADMIN_EMAIL` / `REBASE_ADMIN_PASSWORD`, and **never choose those values,
> or register an account, on the user's behalf.** The env pair still works on
> Cloud for an admin that is not an organization member.

---

## ⚠️ A project with no database never deploys, and never says so

This is the failure this skill exists to prevent. Read it before acting on any
`status` output.

A project created without a database is written `status: "provisioning"` and
sits there **forever**. Nothing is provisioning. The platform is waiting for
`rebase cloud db create`, and the word "provisioning" says the opposite.

`status` answers this directly. Use these two fields and nothing else to decide
whether to wait:

```bash
rebase cloud status --json
```

```json
{
  "status": "provisioning",
  "blockedOn": "no_database",
  "nextAction": "rebase cloud db create --type managed"
}
```

| `blockedOn` | Meaning | What to do |
|---|---|---|
| `null` | The platform is genuinely working | **This is the only value you may poll on.** |
| `no_database` | No database attached | Run the `nextAction` — this state never resolves itself |
| `never_deployed` | Database attached, nothing shipped | `rebase cloud deploy` |
| `last_deploy_failed` | The last deploy failed — in its build, or booting after it | The `nextAction`: `rebase cloud logs` (the build log), or `rebase cloud logs --runtime` when it died booting; fix, deploy again |
| `database_unreachable` | Attached but not answering | `rebase cloud db test` |

> **IMPORTANT FOR AGENTS:** Never poll `status` while `blockedOn` is non-null.
> The value cannot change on its own, so there is no timeout short enough to be
> wrong and none long enough to be right. Run `nextAction`, or stop and report it.

---

## The managed database

Managed PostgreSQL is **CloudNativePG running in-cluster**, not Cloud SQL or
RDS. Every managed database is a CloudNativePG cluster of the project's own, in
the project's own namespace — no other tenant shares it (the shared pool tier is
retired). Three consequences follow, and each one changes what you should do.

### 1. It does not exist until the first deploy

`rebase cloud db create` writes a record. The Postgres cluster, the namespace
and the credentials are created when the project first deploys.

So this is **expected, not a fault**:

```
$ rebase cloud db test
✗ Failed to test database: secrets "postgres-app" not found
```

Do not debug it. Do not retry it. Deploy first; `db test` answers afterwards.
`rebase cloud db create --wait` knows this and returns immediately for a managed
database rather than polling something that cannot appear yet.

### 2. Extensions restart this project's own database

```bash
rebase cloud extensions list
rebase cloud extensions enable vector      # `pgvector` is accepted as an alias
```

`extensions list` marks some with **⟳ restarts DB**. That restart is this
project's database and nothing else's — a single-instance database has no
standby to fail over to, so it is a write outage for as long as the restart
takes. The CLI refuses to do it without `--yes`. Never pass `--yes` to an
extension enable on the user's behalf.

### 3. When the managed database is not the right shape

```bash
# Your own PostgreSQL, anywhere
rebase cloud db create --type byodb --connection-string "$DATABASE_URL" --wait
```

`byodb` is the right answer when the database has to be somewhere the platform
does not run. There is no longer a pooled tier to outgrow: every managed
database is already a CloudNativePG cluster of the project's own, sized with
`rebase cloud compute set --db-cpu`, `--db-memory` and `--db-instances`
(`--storage` is the object-storage mode, not the database volume).

> **A project has exactly one database.** The platform reads its `databases`
> rows with `limit: 1` in three places, so a second row does not add a database —
> it makes it undefined which one the project deploys against. `db create`
> refuses with `code: database_exists` rather than creating one; detach the
> existing database first.

### Reading a database's real location

```bash
rebase cloud db info            # host, port, database, username
rebase cloud db info --reveal   # …and the password (never shown by default)
```

---

## Environment variables

```bash
rebase cloud env list
rebase cloud env set STRIPE_SECRET_KEY=sk_live_… --secret
rebase cloud env unset OLD_KEY
rebase cloud env pull            # write them into a local .env
rebase cloud deploy              # variables apply at the NEXT deploy
```

Values are encrypted at rest and decrypted at deploy time. A change is
**pending** until the next deploy.

### Build-time variables cannot be set here — and the CLI will tell you

<!-- docs-verify: ignore -->
```
$ rebase cloud env set VITE_GOOGLE_CLIENT_ID=1234.apps.googleusercontent.com
✗ VITE_GOOGLE_CLIENT_ID is read by your bundler at BUILD time, and project
  variables are applied at rollout — after the image is built. Setting it here
  would not reach the bundle.
```

(`--json` carries `code: build_time_variable`.)

This is correct and you should not force past it. `VITE_*`, `NEXT_PUBLIC_*`,
`PUBLIC_*` and `REACT_APP_*` are **inlined into the JavaScript by the bundler**
before the image exists. Setting one here produces a variable that is present in
the container and `undefined` in the bundle — nothing fails, the deploy
succeeds, and the app breaks in the browser several steps away from the cause.

A managed deploy builds the frontend on your machine, so put them where that
build reads them — the shell that runs `rebase cloud deploy`, or an env file
Vite loads (the scaffold's `vite.config.ts` sets `envDir` to the project root):

```bash
# .env.production at the project root — committed, read by the bundler at build time
VITE_GOOGLE_CLIENT_ID=1234.apps.googleusercontent.com
```

`VITE_API_URL` is the exception: the deploy builds every static app with it
taken from the shell, blank (same origin) when unset, so a value in an env file
never wins. Same origin is right for an app the backend serves; to point at
another origin, run `VITE_API_URL=https://… rebase cloud deploy`.

`--force` exists for the rare app that genuinely reads such a name at run time.
Do not reach for it to make an error go away.

### Names the platform owns

These are set for every project and cannot be overridden — `env set` refuses
them with `code: env_var_key_reserved`:

`DATABASE_URL` · `DATABASE_DIRECT_URL` · `DATABASE_READ_URL` · `JWT_SECRET` ·
`REBASE_SERVICE_KEY` · `PORT` · `NODE_ENV`

…and the runtime-topology names the platform pins on every pod (`REBASE_ROLE`,
`TRUSTED_PROXY_HOPS`, `REBASE_RATE_LIMIT_STORE`, `REBASE_CRON_SCHEDULER`,
`REBASE_JOB_WORKERS`, `REBASE_MCP_ENABLED`, …). The refusal lists every reserved
name. `REBASE_SERVICE_KEY` cannot be set, but an owner or admin can read it with
`rebase cloud env reveal REBASE_SERVICE_KEY`.

Names that merely look similar (`MY_DATABASE_URL`, `JWT_SECRET_KEY`, `PORTAL`)
are yours to set.

---

## Deploying

```bash
rebase cloud deploy                          # the repository's backend
rebase cloud deploy web                       # a named app
rebase cloud deploy --message "add search"    # label the release
rebase cloud deploy --timeout 600             # bound the wait, in seconds
rebase cloud deploy --no-follow               # return once the build is triggered
```

`deploy` **follows the build to a terminal state and exits non-zero if it
failed**. That is the default on every path — you do not need a poll loop, and
you should not write one. `--wait` is accepted as an explicit spelling of the
same thing.

It then **checks the new version is live** — each app's URL is probed for up to
`--live-timeout` seconds (default 60) — and ends on a summary listing every app,
its URL and whether it answers. Do not `curl` the app afterwards to find out;
read the last line. Relay the URLs to the user. A failure ends on one line naming
the app and the reason.

Which kind of deploy runs is decided by the repository, not by you:

| Situation | What happens |
|---|---|
| `rebase.json` declares `"runtime": "managed"` | A **bundle** deploy — the default for scaffolded projects |
| `--source .` | Uploads the directory and builds a container image |
| Neither | The control plane rebuilds the source it already holds (a git checkout, or an older upload) |

> **IMPORTANT FOR AGENTS:** `--source` on a managed project is **refused**,
> because a source build rewrites the project onto a container image and off the
> platform runtime. `--eject` overrides that refusal. Never pass `--eject` to
> get past this error — it is a one-way change to how the user's project runs.
> (It was spelled `--force` before 0.18.0, and no alias was kept: `--force` on
> `deploy` is now an unknown option.)

---

## Multi-app projects

One container can serve several apps at different paths. Declare them in
`rebase.json`:

```jsonc
{
  "rebase": "^1",
  "apps": {
    "backend": { "type": "backend", "runtime": "managed" },
    "site": {
      "type": "static",
      "root": "frontend",
      "build": "npm run build --workspace frontend",
      "output": "frontend/dist",
      "path": "/"
    },
    "admin": {
      "type": "static",
      "root": "admin",
      "build": "npm run build --workspace admin",
      "output": "admin/dist",
      "path": "/admin",
      "cms": "/admin"
    }
  }
}
```

`path` is a **build-time** input, not only a serving one. An app mounted at
`/admin` must be *built* for `/admin`, or `index.html` loads and every asset
404s — a blank page with nothing in the logs. `rebase build` passes the value as
`REBASE_APP_BASE`:

```ts no-verify
// admin/vite.config.ts
import { rebaseBackendGuard } from "@rebasepro/app/vitePlugin";

export default defineConfig({
    base: process.env.REBASE_APP_BASE ?? "/",
    // Required beside a backend/: `rebase build` refuses a frontend without it.
    plugins: [react(), rebaseBackendGuard()]
});
```

**And no absolute asset paths in `index.html`.** A hand-written
`<link rel="icon" href="/favicon.ico">` is not rewritten by the bundler's base,
so it resolves to the site root. Use the base-relative form:

```html
<link rel="icon" href="%BASE_URL%favicon.ico" />
```

The build refuses a misbuilt app rather than shipping a blank page:

<!-- docs-verify: ignore -->
```
"admin" is declared at /admin but its build emitted assets rooted at /.
    index.html references: /favicon.ico, /assets/index-a1b2.js
    The app would load a blank page. Set `base` from REBASE_APP_BASE in its
    build config
```

### An app on its own hostname

A static app's `path` may be a full `https://` URL instead. The app then answers
only on that hostname, and every app without one keeps answering on all the
others:

```jsonc
"web": {
  "type": "static", "root": "frontend", "output": "frontend/dist",
  "path": "/"
},
"admin": {
  "type": "static", "root": "admin", "output": "admin/dist",
  "path": "https://admin.example.com",
  "cms": "/"
}
```

`admin.example.com` serves `admin`; the project's `*.rebase.website` host and
every other hostname serve `web`. Of the apps that may answer a request, the
longest path wins, and at an equal path the one naming the hostname wins. So
`"https://admin.example.com/cms"` takes only `/cms` on that hostname, and the
rest of `admin.example.com` goes to `web`.

What stays the same:

- **`/api` and the other backend paths answer on every hostname**, before any
  app. The admin calls the API on its own hostname; it needs no API URL or CORS
  change. `https://admin.example.com/api` is refused as a `path`, like `/api`.
- **The build uses the path part.** `https://admin.example.com` builds with
  `REBASE_APP_BASE=/`.
- **`cms` is always a path** — the path on the app's hostname, inside its path
  part. The console's *Open CMS* link then points at `https://admin.example.com/`.
- **A hostname belongs to an app, not a route.** A CMS that is one route of a
  single SPA (`"cms": "/admin"` on `web`) stays at `/admin` on every hostname.
  To give it a hostname, it has to be an app of its own, with its own build.

What `rebase cloud deploy` does with the hostname:

1. Registers it on the project — the same row `rebase cloud domains add`
   writes. A hostname another project holds, or one under the platform's own
   domain, fails the deploy before rollout.
2. If its DNS is already published, verifies it; it is live when the deploy
   finishes, and the platform issues its TLS certificate.
3. If not, the deploy still succeeds and prints the records to create (a TXT
   for ownership, a CNAME to the project — an A at an apex) and the command to
   run afterwards:

```bash
rebase cloud domains verify admin.example.com
```

Until it verifies, `admin` is reachable nowhere: the one hostname it answers on
does not reach the project yet. Removing the app from `rebase.json` does not
remove the hostname — `rebase cloud domains remove` does.

> **IMPORTANT FOR AGENTS:** A deploy of a `rebase.json` with a URL `path`
> registers a custom domain on the project, which is a change to the hosted
> platform like `domains add` — the same "asked in this conversation" rule
> covers it. The DNS records are the user's to publish: hand them the records
> the deploy printed and the `verify` command, and do not poll `verify` in a
> loop — nothing changes until someone edits their DNS zone.

### A function at a path on a static app, and framing by another origin

`routes` on a static app serves a custom function's response at a path on the
app's own address — a sitemap, a feed, a server-rendered page — with no custom
runtime or proxy in front:

```jsonc
"site": {
  "type": "static", "root": "site", "output": "site/dist",
  "path": "https://www.example.com",
  "routes": [
    { "path": "/sitemap.xml", "function": "sitemap" },
    { "path": "/blog/*", "function": "blog" }
  ],
  "frameAncestors": ["https://admin.example.com"]
}
```

- The function sees the request as a call to `/api/functions/<name>` (same
  auth, scopes, rate limit, timeout); `/blog/*` matches `/blog` and everything
  under it and hands the function the rest of the path. The most specific
  route wins, and a route wins over a file of the same path in the build.
- Routes are served by the backend the app is folded into: `rebase build`
  fails on a route naming a function the backend lacks, and
  `rebase cloud deploy` refuses a static app with routes deployed on its own.
- `frameAncestors` adds origins to the app's `frame-ancestors` (default
  `'self'`), so a CMS on another hostname can preview the site in an iframe.
  Each entry is exactly one origin (`https://host[:port]`, or `http://` for
  localhost) — no wildcard, no path; anything else is refused before deploy.

---

## Diagnosing a failed deploy

Work outward, cheapest first:

```bash
rebase cloud status                  # blockedOn / nextAction first, always
rebase cloud logs                    # the last build log
rebase cloud logs --runtime          # the running container's log
rebase cloud deployments list        # history: status, duration, trigger
rebase cloud debug                   # read-only diagnosis of a misbehaving deploy
rebase cloud metrics                 # live CPU / memory / disk, restarts, crash reasons
```

Recovering:

```bash
rebase cloud rollback                # back to the last successful deploy
rebase cloud cancel --yes            # stop an in-flight build
rebase cloud restart --yes           # restart the running instances
```

### Telling a platform failure from a project failure

This distinction decides whether there is anything to fix in the code at all,
and getting it wrong is expensive.

**A `403` naming a `system:serviceaccount:` is a PLATFORM problem.** It means the
control plane's own Kubernetes credentials were refused. Nothing in the project
can grant them — not the collections, not `rebase.json`, not a deploy flag. The
CLI now says so:

<!-- docs-verify: ignore -->
```
$ rebase cloud deploy
✗ Deploy failed: the platform's own cluster credentials were refused by Kubernetes.
  cronjobs.batch is forbidden: User "system:serviceaccount:rebase-control-plane:control-plane"
  cannot create resource "cronjobs" in API group "batch" in the namespace "tenant-my-app"
  This is a platform-side permission, not something your project can grant.
  Nothing in your code, collections or deploy flags will change it —
  report it with the message above rather than retrying or changing the project.
```

> **IMPORTANT FOR AGENTS:** On `platform_permission_denied`, **stop and report**.
> Do not retry. Do not delete cron jobs, functions or collections to see whether
> they are the cause — they are not, and you will delete working code. This
> happened: three cron jobs were removed from a real project to A/B a
> `cronjobs.batch` 403, and the 403 was unrelated to all three.

Add `--debug` to any failing command to get the untouched error body (on stderr,
so it never corrupts `--json` output):

```bash
rebase cloud deploy --debug
```

For a platform admin, one command answers the whole question:

```bash
rebase cloud clusters verify <cluster-id> --baseline
```

It reports `permissions.allowed` and `permissions.denied`, which is what names a
missing RBAC grant directly. It exits non-zero when the verdict is `unusable`.

---

## Domains

```bash
rebase cloud domains list
rebase cloud domains add app.example.com     # prints the DNS records to create
rebase cloud domains verify app.example.com  # once DNS has propagated
rebase cloud domains remove app.example.com
rebase cloud domains primary example.com          # the canonical one links are built from
rebase cloud domains redirect www.example.com     # answer it with a 308 to the primary
rebase cloud domains redirect www.example.com --off
```

TLS is issued automatically once verification passes.

Every verified domain serves the project as itself, and two domains are two
origins: Google sign-in (`origin_mismatch`), cookies and passkeys each work on
one and fail on the other. When a project answers on both an apex and `www.`,
make one `primary` and `redirect` the other — a permanent redirect (308) that
keeps the path and the query. It is per domain and off by default, so an `api.`
host beside the site keeps serving; it takes effect while the domain is
verified and another one is primary, and never applies to a domain an app is
served on. Like `domains add`, it changes the hosted platform: only when the
user asked.

A deploy also registers every hostname `rebase.json` gives a static app as its
`path`, and verifies it when the records are already there — see
[An app on its own hostname](#an-app-on-its-own-hostname). Those hosts show up
here like any other.

---

## Resources and cost

There are no plan tiers. A project is priced by the resources it reserves, and
each one is a dial:

```bash
rebase cloud compute                       # what this project reserves, and €/month
rebase cloud compute set --cpu 500m --memory 1Gi
rebase cloud compute set --db-instances 2 --db-memory 4Gi
rebase cloud compute set --autoscale-max 5 --autoscale-cpu-target 70
```

`compute` itemises the monthly quote line by line. Empty means the platform
default.

`rebase cloud resources` is a different question: what the platform holds for
the project against what its code declares — each database and bucket, whether
the last deploy still declares it, whether the platform made it. A deploy never
removes a provisioned database when its declaration goes; it keeps, binds and
bills it until `rebase cloud resources prune database <key>` (asks; `--yes`
off a terminal). Do not prune unasked.

---

## Output is JSON whenever stdout is not a terminal

Every `rebase cloud` command switches to machine-readable output when stdout is
piped or redirected, when `--json` is passed, or when `REBASE_JSON=1` is set.
**An agent running these through a shell always gets JSON**, never the
human-formatted output.

The one exception is `rebase cloud deploy`, which prints its summary even when
piped, because the person you are working for needs its URLs and its live/not-live
line. Pass `--json` to get one object instead (`apps`, `hosts`, `live`,
`liveChecks`, `durationMs`, `deploymentId`).

The contract is **one JSON value on stdout and nothing else**. Narration,
warnings and errors go to stderr, so `stdout | jq` is always safe.

```bash
rebase cloud status --json | jq -r '.blockedOn // "ready"'
```

Failures are JSON too, and carry a stable `code`:

```json
{ "error": { "message": "…", "code": "platform_permission_denied", "platform": true } }
```

To see the human output from a non-interactive shell, wrap the call:

```bash
script -q /dev/null rebase cloud status
```

---

## Discovering flags

`--help` prints a page and never runs the command. It works per action, not just
per group:

```bash
rebase cloud --help
rebase cloud projects create --help
rebase cloud deploy --help
rebase cloud db create --help
```

Piped, `--help` returns a structured description of the command — usage,
every flag, notes and examples — which is the right way for an agent to discover
a command it has not used before.

---

## CI and agents: `REBASE_TOKEN`

A token acts as the account that created it, narrowed to a few capabilities on
one project (or, for `billing`, `audit` and `notifications`, one organization). Create it from a signed-in terminal, then give it to CI as
`REBASE_TOKEN`:

```bash
rebase cloud tokens create --project shop --can deploy,logs --expires-in 90
# → export REBASE_TOKEN=rk_live_…   (printed once)
```

- With `REBASE_TOKEN` set, every `rebase cloud` command authenticates with it and
  never reads or writes the stored `cloud login` session. `rebase cloud whoami`
  then shows what the token may do and on which project.
- `--can` takes `deploy`, `logs`, `env`, `database`, `backups`. Each becomes
  scopes narrowed to that project (`project:deploy:<id>`, …) plus the data and
  function scopes the commands call. The token is a personal API key on the
  control plane: it never holds more than its account does when used.
- `--can` also takes `billing`, `audit` and `notifications`, which act on one
  organization: `--org <id>`, else the project's organization, else the selected
  one. Reading the audit log needs `--can audit`.
- A token cannot `tokens list` / `create` / `revoke` — those need the signed-in
  session (`session_required`). No capability grants a backup restore or a PITR
  `restore` / `cutover`: those stay with a signed-in owner or admin.
- `token_rejected` means the token expired, was revoked, or is for another
  control plane. Create a new one; do not fall back to a password.

## Connecting Claude to every project

One hosted MCP connector reaches all of the user's projects: `https://app.rebase.pro/mcp`.

1. In Claude: **Settings → Connectors → Add custom connector**, that URL, sign in
   with the Rebase account. Every Cloud project of their organizations is there.
2. For each **self-hosted** server, once:

   ```bash
   rebase cloud connect https://their-app.com
   ```

   It adds the server to the account and prints `REBASE_PLATFORM_TOKEN_KEY` and
   `REBASE_PLATFORM_TOKEN_AUDIENCE`. They go on **that server** (in its folder the
   command offers to write them to `.env`); after a restart the command sees it
   answer and prints `Connected`. Rerunning it is safe and reports the state.

Then Claude names any of them by name or host. On a self-hosted instance the
connector reads and changes data, reads the schema and runs cron jobs; deploys,
env vars and logs are Cloud-only and it says so. The server needs Rebase 0.28.1
or later at a public https address; adding one needs the organization's owner or
admin role. `rebase cloud connect --list` shows them, `--remove <url>` takes one
out.

## Command reference

| Command | What it does |
|---|---|
| `rebase cloud login` / `logout` / `whoami` | Session |
| `rebase cloud tokens list` / `create --can …` / `revoke <id>` | Tokens for CI and agents (`REBASE_TOKEN`) |
| `rebase cloud use` | Select the active organization |
| `rebase cloud link` / `unlink` / `open` | Link this directory to a project |
| `rebase cloud connect <url>` / `--list` / `--remove <url>` | Add a self-hosted server to the Rebase connector in Claude |
| `rebase cloud init --claim` | A live backend with no account, and a link to claim it within 72 hours |
| `rebase cloud claim` | That link again, and how long is left |
| `rebase cloud projects list` / `create` / `info` / `delete` | Projects |
| `rebase cloud db list` / `create` / `info` / `connect` / `test` | Databases (`connect` tunnels a local port to it; owner or admin) |
| `rebase cloud db backup list` / `create` / `restore` / `status` / `download` | Backups |
| `rebase cloud db pitr status` / `restore` / `cutover` / `discard` | Point-in-time recovery |
| `rebase cloud deploy` / `logs` / `deployments list` | Ship and observe |
| `rebase cloud deploy --git [<branch>]` | Build on the control plane from the connected repository (on the managed runtime it needs `--eject`) |
| `rebase cloud deploy-hooks` / `create` / `revoke <id>` | Secret URLs a git host or CI calls to deploy; `create` prints the URL once |
| `rebase cloud alerts` / `ack <id>` / `snooze <id> --hours <1-168>` | The project's incidents |
| `rebase cloud previews` / `previews delete <name>` | Builds served at their own address by `deploy --preview` |
| `rebase cloud rollback` / `cancel` | Recover |
| `rebase cloud start` / `stop` / `restart` / `status` / `metrics` / `debug` | Operate; `metrics --runtime` is requests, errors and latency per surface, `--history` over time |
| `rebase cloud cron` | The deployed app's cron jobs and their runs. Read-only |
| `rebase cloud env list` / `set` / `unset` / `reset` / `reveal` / `pull` | Configuration |
| `rebase cloud domains list` / `add` / `verify` / `remove` / `primary <domain>` / `redirect <domain> [--off]` | Custom domains; `primary` makes a verified one canonical, `redirect` answers another with a 308 to it |
| `rebase cloud extensions list` / `enable` / `disable` | Postgres extensions |
| `rebase cloud settings show` / `set` | Name, branch, repo, subdomain, `--studio on\|off` (Studio access, which `--project` commands and `cloud guests` go through) |
| `rebase cloud compute` / `compute set` | What it reserves, and what it costs |
| `rebase cloud resources` / `resources prune database <key>` | What the platform holds against what the code declares |
| `rebase cloud storage` / `storage create` / `storage attach` | Object storage |
| `rebase cloud notifications` / `add <url>` / `test <id>` / `remove <id>` | Deploy, backup, billing and usage events to Slack, Discord or any URL |
| `rebase cloud orgs list` / `create` / `rename` / `delete` / `members` | Organizations |
| `rebase cloud billing` / `billing setup` / `billing checkout` / `billing email <address>` | Card on file, and where invoices go |
| `rebase cloud usage` / `usage org` | Requests used this month against the allowance, and the overage so far |
| `rebase cloud activity` | The organization's audit log, newest first |
| `rebase cloud app-key` / `app-key rotate` | The app key `init --claim` wrote; owners and admins |
| `rebase cloud service-key` / `service-key rotate` | `REBASE_SERVICE_KEY`; owners and admins |
| `rebase cloud clusters` / `clusters add` / `clusters verify` | Platform admin |

`rebase cloud webhooks` is retired: it exits 1 with `command_retired`. For a POST
when rows of your own tables change, use a `WebhookDispatcher` in app code.

Global flags on every one of them: `--project, -p <slug>`, `--json`,
`--url <origin>`, `--yes, -y`, `--debug`.

Destructive commands ask first (`env unset`, `compute set` with its price
quote, `settings set --subdomain`, `db access enable`, `projects create`,
`orgs members role`, `orgs invites revoke`, …). With no terminal, or under
`--json`, they refuse with `confirmation_required`; `--yes` answers for a
script. A command whose control-plane route is not deployed answers
`not_served` instead of a bare 404.

The app's own data, users, cron, logs, functions and files are not under
`rebase cloud`: `rebase data`, `rebase users`, `rebase cron`, `rebase logs`,
`rebase functions`, `rebase storage` and `rebase api` take `--project <slug>`
and go through the console's Studio proxy (see the **`rebase-basics`** skill:
`../rebase-basics/references/cli-commands.md`).

---

## ⛔ Agent rules

**Never run a command that changes the hosted platform unless the user asked in
the current conversation.** That includes `deploy`, `projects create`,
`projects delete`, `db create`, `env set`, `domains add`, `rollback`, `stop`,
`restart`, `compute set`, `extensions enable`, `tokens create` / `tokens revoke`
and `connect` / `connect --remove`.

**Never pass these to get past an error:**

| Flag | What it actually does |
|---|---|
| `--eject` on `deploy` | Moves the project off the managed runtime onto a container image. One-way. |
| `--force` on `env set` | Stores a build-time variable that will silently never reach the bundle |
| `--yes` on `extensions enable/disable` | Restarts the project's database — a write outage while it comes back |
| `--yes` on `projects delete` | Deletes the project |

**Never retry or "fix" a `platform_permission_denied`.** Report it.

**The local MCP tools `rebase_cloud_deploy` (production), `rebase_cloud_env_set`
(production), `rebase_cloud_rollback` and `rebase_cloud_provision` take
`confirm: true`.** Without it they answer what they would do and do nothing.
Show that plan to the user and call again with `confirm: true` only after they
agree — never set it on the first call. A preview deploy and a preview variable
need none.

**Safe to run unasked:** `status`, `logs`, `deployments list`, `env list`,
`resources`, `compute`, `metrics`, `debug`, `db info`, `domains list`, `extensions list`,
`connect --list`, and any `--help`.

---

## Related skills

- **rebase-deployment** — Docker, Kubernetes, AWS/GCP/Azure/Hetzner, Railway,
  Render, and the `serveSPA()` / health-check / graceful-shutdown details that
  apply to every deployment target including this one.
- **rebase-basics** — project layout, `rebase.json`, the CLI in general.
- **rebase-backend-postgres** — schema, migrations, `rebase db push`.

## References

- **Documentation:** [rebase.pro/docs](https://rebase.pro/docs)
- **Console:** [app.rebase.pro](https://app.rebase.pro)
- **Apps and repositories:** `website/src/content/docs/docs/architecture/apps-and-repositories.md`
- **Cloud CLI source:** `packages/cli/src/commands/cloud/`
