# CLI command reference

## Global Options

| Option | Description |
|--------|-------------|
| `--version`, `-v` | Show CLI version number |
| `--help`, `-h` | Show help message |
| `--debug` | Print the stack trace when a command fails (or `REBASE_DEBUG=1`) |

## Full Command Reference

### Project Lifecycle

| Command | Description |
|---------|-------------|
| `rebase init [name]` | Scaffold a new Rebase project interactively |
| `rebase dev` | Start development server (backend + frontend concurrently) |
| `rebase build` | Build the apps declared in rebase.json into a deployable bundle |
| `rebase start` | Run the built bundle, as a deployment does, in the `NODE_ENV` you set (the scaffold's `.env` says `development`) |
| `rebase upgrade` | Move every `@rebasepro/*` pin in the project to one release (`--to <version\|tag>`, default `latest`), then install. `--dry-run`, `--no-install`, `--allow-downgrade`, `--drop-local-overrides`, `--json` |
| `rebase apps list` | Show the apps `rebase.json` declares and their build outputs. `apps init` writes a `rebase.json` inferred from the project and takes no app name; `--force` replaces an existing one, keeping each app's name, `path` and `cms` (0.25+); `apps config <app>` prints an app's client configuration |
| `rebase eject [app]` | Take ownership of the server process: writes the backend entrypoint and a Dockerfile, and sets `runtime: "custom"`. One-way — platform runtime upgrades stop reaching the project. `--dry-run` lists the changes |

`rebase normalize-imports <dir>` completes the relative imports in compiled
output so Node ESM can load it; `--check` reports instead of rewriting.

### `rebase init` Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--headless` | — | Backend only: no admin panel, no `backend/schema`. Prompts when omitted |
| `--template` | `-t` | Starter template to scaffold from: `blog` (default), `ecommerce` or `blank` |
| `--git` | `-g` | Initialize a git repository |
| `--install` | `-i` | Install dependencies with the detected PM |
| `--no-install` | — | Install nothing, and do not ask |
| `--database-url` | — | PostgreSQL connection string (skip prompt) |
| `--introspect` | — | Generate `backend/schema` from that database (implies `--template blank`; needs `--install`) |
| `--project` | — | Link the scaffold to a Rebase Cloud project |
| `--setup-key` | — | One-time key authenticating that cloud link (with `--project`) |
| `--yes` | `-y` | Non-interactive mode (use all defaults; git init and the install are skipped unless `--git` / `--install` is passed) |
| `--agent` | `-a` | Install the skills and register the MCP server for these AI agents (`claude,cursor`, or `all`). Without it the prompt asks, pre-ticking the agents installed on the machine; under `--yes`, none |

#### What gets scaffolded

```bash
rebase init my-api   --headless   # backend/ alone — REST, auth, storage, realtime, backups. No backend/schema, no UI, no React
rebase init my-app                # backend/ (with backend/schema) + frontend/ (with src/cms) — the backend plus the admin panel (default)
```

`--headless` reads the tables from the database at boot rather than from
`backend/schema`, so there is nothing to declare and nothing to keep in sync. It
serves only tables with `ENABLE ROW LEVEL SECURITY` — a table without RLS has no
authorization model, so serving it would hand every row to every logged-in user.

`dev`, `build` and `start` detect a missing `frontend/` and run backend-only.

```bash
# Interactive mode
rebase init my-app

# Non-interactive — scaffold with a remote database and introspect it
rebase init my-app --yes --database-url "postgresql://user:pass@host:5432/db" --introspect --install
```

### `rebase dev` Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--backend-only` | `-b` | Only start the backend server |
| `--frontend-only` | `-f` | Only start the frontend server |
| `--port` | `-P` | Set the backend port (default: deterministic per-project hash) |
| `--database-url` | — | Use this Postgres, ahead of everything else |
| `--docker` | — | Use the project's docker-compose `db` service, starting it if needed |
| `--no-db` | — | Start no database at all |

> **IMPORTANT FOR AGENTS:** Each project automatically receives a **unique default port** derived from its directory path (range 3001–3999), preventing collisions when running multiple Rebase instances. The resolved port is saved to `.rebase-dev-port` for affinity across restarts. The backend URL is saved to `.rebase-dev-url` so scripts can read it. The frontend receives `VITE_API_URL` automatically.

**Port resolution order:**
1. Explicit `--port` flag (highest priority)
2. `PORT` in the shell environment (a `PORT` in `.env` is not read for this)
3. Previously saved port from `.rebase-dev-port` (port affinity)
4. Deterministic hash from project path (unique per project)

**Generated files stay current on their own.** On startup and on every save under `backend/schema/`, the CLI regenerates the Drizzle schema (`backend/src/schema.generated.ts`) and the SDK types (`generated/sdk/`). There is no flag for it and nothing to run by hand.

```bash
# Start everything (default)
rebase dev

# Backend only on a specific port
rebase dev --backend-only --port 3005
```

### `rebase build`

Builds the apps declared in `rebase.json`. For the `backend` app this produces a **bundle** — compiled tables, functions and schema plus a manifest — which is the artifact the runtime (and `rebase start`) loads. For `static` apps it runs the declared build command and reports where the output landed.

Takes an optional list of app names; with none, every app in the manifest is built.

| Option | Alias | Description |
|--------|-------|-------------|
| `--output` | `--out` | Bundle output directory (default: `dist-bundle`) |
| `--skip-type-check` | | Compile without type checking (iteration only) |
| `--skip-schema` | | Do not regenerate the database schema from the tables |
| `--no-static` | | Do not fold the frontend assets into the backend bundle |
| `--skip-static-build` | | Fold already-built assets without re-running the app's build |
| `--no-vendor` | | Do not install the dependencies into the bundle (they install on every start instead) |
| `--vendor` | | Install them into the bundle whatever the tree's size |
| `--workspace` | | Run every workspace's own `build` script instead of bundling |
| `--help` | `-h` | Show build command help |

A frontend whose `vite.config.ts` does not use `rebaseBackendGuard()` (from
`@rebasepro/app/vitePlugin`) is refused: the guard fails the build when any
frontend module resolves into `backend/`, which would ship server code to the
browser. The frontend imports `backend/` as types only (`import type`).
`frontend/src/cms/ui-config.json` goes into the bundle as `entry.uiConfig`.

> **IMPORTANT FOR AGENTS:** "Build for production" means the default (bundle) path. `--workspace` runs each workspace's own build script and produces **no** bundle, so `rebase start` will have nothing to run. A project with no `rebase.json`, or one whose backend has been ejected, falls back to that path automatically.

```bash
# Build every app declared in rebase.json
rebase build

# Only the backend bundle, into a custom directory
rebase build backend --output build/bundle
```

### `rebase start`

Runs a built bundle through the Rebase runtime — the same path the official container image takes. Automatically sets `DOTENV_CONFIG_PATH` if a `.env` file is found. With no bundle present it falls back to the backend workspace's own `start` script.

| Option | Alias | Description |
|--------|-------|-------------|
| `--bundle` | | Bundle directory (default: `dist-bundle`) |
| `--workspace` | | Run the backend workspace's own `start` script |
| `--help` | `-h` | Show start command help |

```bash
rebase build && rebase start
```

`rebase start` starts no database. The scaffold's `.env` has no `DATABASE_URL`
(it uses the managed one), so a local run is
`DATABASE_URL="$(rebase db url)" rebase start`; without one it stops before
booting and prints that line.

### Schema Commands

| Command | Description |
|---------|-------------|
| `rebase schema generate` | Generate the Drizzle schema from the tables in `backend/schema` |
| `rebase schema introspect` | Read a live database → write one `defineTable` module per table into `backend/schema`, and an export line for each in its `index.ts`. Every table it writes says `rls: "admin-only"`: write the real rules before anyone but an admin needs the rows |
| `rebase schema stale` | Report generated schema files the tables have moved past. `--fix` regenerates them |
| `rebase schema reconcile` | Through the running backend (Rebase Cloud included): relax NOT NULL on columns made nullable and on undeclared columns that block inserts (data kept), and drop the undeclared columns named with `--drop <table>.<column>`. Prints the plan and asks; show it to the human and never pass `--yes` for them |
| `rebase schema --help` | Show schema command help |

> **IMPORTANT FOR AGENTS:** Schema commands are delegated to the active database driver plugin (e.g. `@rebasepro/server-postgres`). The plugin must be installed in `backend/package.json` or the command will fail with `Could not detect an active database plugin`.

#### `schema generate` Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--schema-dir` | — | The schema directory, whose `index.ts` exports the tables (default: `backend/schema`, or `rebase.json`'s `apps.<backend>.tables`) |
| `--output` | `-o` | Output path for generated schema |
| `--watch` | `-w` | Watch for changes and regenerate automatically |

#### `schema introspect` Options

| Option | Alias | Description |
|--------|-------|-------------|
| `--schema-dir` | — | Where the table modules are written (default: `backend/schema`) |
| `--schema` | — | The Postgres schema to read |
| `--force` | — | Overwrite table modules that are already there |
| `--data-inference` / `--no-data-inference` | — | Sample up to 100 rows per table to detect formats, or read the structure only. Without either it asks; with no terminal, structure only |
| `--database-url` / `--docker` | — | Read that database, or the compose one, instead of the one `rebase db url` prints |

### Database Commands

| Command | Description |
|---------|-------------|
| `rebase db push` | Apply schema directly to database (development only). `--dry-run` prints the SQL; a change that drops data needs `--allow-destructive` |
| `rebase db generate` | Generate SQL migration files |
| `rebase db migrate` | Run pending SQL migrations. `--refuse-destructive` applies nothing when a pending file drops or narrows data; `--baseline <version>` for a database boot already created |
| `rebase db branch` | Database branching (create, list, switch, delete, info, diff, merge, prune) — needs a real PostgreSQL. `merge <name>` shows the diff, asks, and writes the branch's row changes onto its parent (`--on-conflict abort\|branch\|target`, `--skip-blocked`); `delete`, `merge` and `prune` ask first, and with no terminal they need `--yes` |
| `rebase db backup` | Write a backup of the current database (default `./backups` where you run `rebase`; unknown options are refused) |
| `rebase db backups list` | List the backups taken so far |
| `rebase db restore` | Restore the database from a backup |
| `rebase db pull` | Copy another database into local development: `--from <url>`, optionally `--anonymize` (name-based and best-effort, in one transaction: if it fails, the affected tables are emptied and named and it exits 1). One-directional — it can never write to a remote database. (Turning a database into `defineTable` files is `rebase schema introspect`) |
| `rebase db url` | Print the connection string this project uses — nothing else goes to stdout, so it pipes. After `rebase dev --docker` it, like every command, uses the Docker database until a `rebase dev` without the flag |
| `rebase db stop` | Stop the managed local database. It comes back on the same port, and a running `rebase dev` reconnects once any command starts it again |
| `rebase db reset` | Delete and recreate the managed local database |
| `rebase db request-role migrate --to <role>` | Move this database to new request role(s): re-creates their grants and policies here only, and records them (`--dry-run` prints the plan) |
| `rebase db provision --print` | Print the SQL that sets up the request role, for a DBA to run |
| `rebase db --help` | Show database command help |

<!-- docs-verify: ignore -->
> **IMPORTANT FOR AGENTS:** There is no `rebase db studio`. The CLI accepts exactly
> the subcommands above and exits 1 on anything else.

`push`, `generate` and `migrate` take `--schema-dir <dir>` like the schema
commands, and compile the tables first: a table the server would refuse stops
them with a `SchemaDefinitionError` that names the table, the column and the fix.

> **IMPORTANT FOR AGENTS:** Like schema commands, `push`, `generate`, `migrate`, `branch`, `backup`, `backups`, `restore`, `request-role` and `provision` are delegated to the active database driver plugin, which provides the actual implementation. `url`, `pull`, `stop`, `reset` and `branch switch` are answered by the CLI itself.

```bash
# Development workflow (fast, no migration files)
rebase schema generate && rebase db push

# Production workflow (versioned migrations)
rebase schema generate
rebase db generate
rebase db migrate

# Create a database branch and work on it
rebase db branch create feature_auth
rebase db branch switch feature_auth
rebase db branch switch --off   # back to the main database
```

### Explore

| Command | Description |
|---------|-------------|
| `rebase console` | New in 0.25. A Node REPL with the project open: `rebase` (`dataAsAdmin`, `sql(query, { params })`, `withAuth(user)` → `{ data }`) and the project's tables (as `collections`) in scope, top-level await. Opening the database changes nothing in it |

| Option | Alias | Description |
|--------|-------|-------------|
| `--eval` | `-e` | Run this code instead of the REPL, print its awaited result as JSON on stdout, and exit 1 if it throws |
| `--schema-dir` | — | The schema directory (default: `backend/schema`) |
| `--database-url` | — | Open this database instead of the project's |
| `--docker` | — | Use the database from docker compose, starting it if needed |

The database is resolved as `rebase db push` resolves it — the managed one is
started if that is what the project uses. `--eval` takes an expression (its
value is the result) or a function body (`return` gives the result).

```bash
rebase console
rebase console -e "rebase.dataAsAdmin.posts.find({ limit: 5 })"
rebase console -e "const u = await rebase.withAuth({ uid: 'u1', roles: ['user'] }); return (await u.data.posts.find()).data"
rebase console -e "rebase.sql('select count(*) from posts')" | jq .
```

The same object from a script is `openRebase` from `@rebasepro/server-postgres`
— see *Exploring data from a script* in the `rebase-basics` skill.

### SDK Generation

| Command | Description |
|---------|-------------|
| `rebase generate-sdk` | Generate a typed JS/TS SDK from the tables in `backend/schema` |

| Option | Alias | Default | Description |
|--------|-------|---------|-------------|
| `--schema-dir` | — | `backend/schema` (or `rebase.json`'s `apps.<backend>.tables`) | The schema directory |
| `--output` (or `--out`) | `-o` | `./generated/sdk` | Output path for generated SDK |
| `--register` | — | — | Also type server-side data (`dataAsAdmin`, a function's or cron's `rebase`): writes the types and the `Register` declaration to `backend/generated/` and remembers it in `rebase.json` |
| `--from` / `--token` | — | — | Fetch the schema from a running project (`link` = this checkout's linked one) instead of `backend/schema`; the token defaults to `$REBASE_SERVICE_KEY` |

The generator compiles the tables `backend/schema/index.ts` exports — the same tables the backend serves — and a table the compiler refuses is an error, as it is at boot.

```bash
rebase generate-sdk --schema-dir ./backend/schema --output ./generated/sdk
```

### Auth Commands

| Command | Description |
|---------|-------------|
| `rebase auth reset-password` | Reset a user's password — through the running backend when it has one and a service key, otherwise directly in the database |
| `rebase auth --help` | Show auth command help |

| Option | Alias | Default | Description |
|--------|-------|---------|-------------|
| `--email` | `-e` | (required — or pass as positional arg) | User's email address |
| `--password` | `-p` (deprecated: `-p` is `--project` elsewhere) | one is generated and printed | New password |

```bash
# With flags
rebase auth reset-password --email user@example.com --password MyNewPass!

# Positional args
rebase auth reset-password user@example.com MyNewPass!
```

### A running app

Act on a running app through its own API, so row-level security, field access, hooks and storage policies apply. Every one takes the same target flags: none (the `REBASE_BASE_URL`, else the running `rebase dev`, with the service key from `.env`), `--url <server>`, `--project <slug>` (a Rebase Cloud project, through the console's Studio proxy — owners and admins, Studio on), `--cloud` (the linked project), `--token <bearer>`, `--session` (after `rebase auth login`), `--anon`; plus `--json` (also when piped) and `--yes` (destructive ones ask first, and refuse with `confirmation_required` when nobody can answer).

| Command | Description |
|---------|-------------|
| `rebase api [METHOD] <path>` | Any route, with the project's credential: `-f k=v` / `-F k=typed` (query on GET, body otherwise — a field alone never writes), `--input <file>`, `-H`, `--include`. Non-2xx exits 1 |
| `rebase data query <table>` | Rows: `--where status=eq.published` (the API's own filter syntax), `--order-by col:desc`, `--limit`, `--fields`, `--include`, `--all`, `--format table\|json\|ndjson\|csv` |
| `rebase data get\|count\|aggregate <table>` | One row by id; a count with `--where`; `--select "count(),sum(total)" --group-by status` |
| `rebase data insert\|update\|delete <table> [<id>]` | `--data '{…}'` or `--file`; update/delete take `--where` for many rows (count, then confirm) |
| `rebase data import <table> --file rows.csv` | Bulk writes from JSON, NDJSON or CSV; `--upsert <column>` |
| `rebase data history\|revert\|watch <table>` | Row history and revert (history on); `watch` tails changes over the realtime socket |
| `rebase schema show [table] [--remote]` | The tables and their columns: from `backend/schema`, or as the server serves them. Read this before `data query` |
| `rebase users list\|get\|create\|update\|delete\|reset-password\|mfa-reset\|roles\|guests` | Accounts; `create <email> --role admin`, `update <email> --add-role editor`, `guests prune --older-than 30d --yes` |
| `rebase cron list\|get\|logs\|run\|enable\|disable\|reset` | Scheduled jobs; on Cloud, reads need log access and the rest owner/admin with Studio on |
| `rebase logs [-f]` | The server's log buffer (`--level`, `--source`, `--search`); on `--project` it is `rebase cloud logs --runtime` |
| `rebase functions list\|invoke <name> [path]` | Your `backend/functions` routes; `invoke` takes `rebase api`'s flags. `--anon` shows what a visitor gets |
| `rebase storage ls\|cp\|rm\|url\|stat` | Stored files; the stored side starts with a colon: `rebase storage cp <file> :avatars/<name>` |
| `rebase rls simulate --role anon` | What a role, user (`--user`) or key (`--key`) would read, table by table. Needs `rebase auth login` (an admin's own session) |
| `rebase auth login\|logout\|whoami` | A person's session on the app, in `~/.rebase/sessions.json`; `--session` sends it |
| `rebase auth emails [--latest] [--links]` | The dev mailbox: sign-in, reset and magic-link mail a server with no SMTP_HOST captured |
| `rebase auth keys [list\|create\|revoke]` | Your own personal API keys (`auth.personalKeys: true`) |

> **IMPORTANT FOR AGENTS:** `rebase schema show --remote` gives the real column names; `rebase data query <table> --json` then reads rows the way the app's users would (as the admin role with the service key — pass `--token` or `--session` to see a narrower view). `rebase auth emails --latest --links` hands you the link a sign-up or reset flow sent.

### Diagnostics

| Command | Description |
|---------|-------------|
| `rebase doctor` | Detect three-way schema drift between the tables in `backend/schema`, the Drizzle schema, and live DB. `--policies` also audits the RLS policies (the CI-gate form) |
| `rebase verify` | Offline checks that the tables are safe to ship: they compile, `rls` coverage of per-user tables, migration freshness, and `frontend/src/cms` read statically against the tables (`cms-unknown-table`, `cms-unknown-field`, `cms-hidden-required`, `cms-duplicate-customization`, `cms-not-static`, `cms-ui-config-not-mounted`, `cms-backend-guard-missing`). `--live` also checks DATABASE_URL (migrations applied, the rls-check audit); `--json`, `--quiet`. Exits 1 on an error, not on a warning |
| `rebase status` | Show every declared resource (databases, buckets, topics, queues, crons, functions) and whether the variables it reads are set. `--json` for scripts |
| `rebase resources` | List the resources this project declares, declared and implicit. `--write` regenerates the committed resource graph; `--check` fails when it is stale, and `--check --json` is the CI form (error envelope, exit 1) |

> **IMPORTANT FOR AGENTS:** `rebase doctor` compares the tables in `backend/schema`, the generated Drizzle schema (`schema.generated.ts`), and the actual PostgreSQL database. Run it after any manual DB changes or when suspecting schema drift.

### API Keys

| Command | Description |
|---------|-------------|
| `rebase api-keys list` | List the service API keys: kind, scopes, roles |
| `rebase api-keys get <id>` | Show one key |
| `rebase api-keys create` | Create a service key: `--name`, and `--scopes data:read:posts,cron:write` (comma-separated or repeated) or `--full-access` (every scope you hold, less `keys:*`); optionally `--roles admin`, `--rate-limit`, `--expires-in <days>` or `--expires-at <ISO date>` |
| `rebase api-keys update <id>` | Change a key's `--name`, `--scopes`, `--roles`, `--rate-limit` / `--no-rate-limit`, `--expires-in` / `--expires-at` / `--no-expiry`; only what you name changes |
| `rebase api-keys revoke <id>` | Revoke a key (asks first; `--yes` for a script) |
| `rebase api-keys scopes` | List every scope the backend knows, including the app's own, and which you hold |
| `rebase api-keys --help` | Show API key command help |

`--permissions`, `--admin` and `--expires` are gone; the command names the option that replaced each.

### Agent Skills

| Command | Description |
|---------|-------------|
| `rebase skills install` | Install these skills for your AI coding assistant. `--agent claude,cursor` (or `all`) skips detection, and is required without a TTY. `--mcp` also registers the MCP server, `--hooks` the Claude Code `rebase verify` hook; `--force` replaces edited files |
| `rebase skills --hooks` | Install only the Claude Code hook that runs `rebase verify --quiet` after each edit under `backend/schema/` or `frontend/src/cms/` |

### Other commands

| Command | Description |
|---------|-------------|
| `rebase generate view <slug>` | Scaffold a custom admin screen; `--collection <slug>` makes it a record tab (`--name`, `--icon`, `--dry-run`, `--force`) |
| `rebase storage orphans` | List the stored files no row names (`--delete` to delete them) |
| `rebase storage move` | Copy a folder of files to another storage source (`--from`, `--to`, `--prefix`, `--delete-source`, which asks first) |
| `rebase migrate collections-to-tables [dir]` | Move a project from `config/collections` to `backend/schema` + `frontend/src/cms`, proven by byte-identical SQL. `--dry-run`, `--check`, `--json`, `--force`, `--skip-sdk-calls`. See `rebase-tables/references/migrate-from-collections.md` |
| `rebase migrate sdk-calls [dir]` | Rewrite the project's own SDK calls for the rename: `data.collection("x")` → `data.table("x")` and the rest. `--dry-run`, `--json`, `--force` |
| `rebase cloud …` | Rebase Cloud: `login`, `link`, `deploy`, `tokens create`, and more — `rebase cloud --help` (see the `rebase-cloud` skill) |

### Usage Sharing

| Command | Description |
|---------|-------------|
| `rebase telemetry` | Anonymous usage sharing, opt-in and off by default. Subcommands `status` (default), `show` (the exact payload), `enable`, `disable` |
