# Scribase documentation (full text)

> Scribase is an application cloud built for coding agents: Postgres, Auth, Storage, Realtime and Edge Functions per project, managed through a /v1 control API, a CLI, an SDK and an MCP server. An agent goes from an empty folder to a live backend with `npx scribase init --temp --yes --json`, no account and no pasted key.

---

Source: https://docs.scribase.com/docs/hosted

# Hosted quickstart

From "no account" to a live backend with its URL and key in your app, in about
a minute. There is nothing to configure: region, database engine and keys are
handled for you.

## 1. Sign up

Open [console.scribase.com/signup](https://console.scribase.com/signup) and
choose **Continue with Google**, **Continue with GitHub**, or an email and a
password.

## 2. Add a card

Hosted Scribase starts with a one-time **$1 card check**, paid through Creem
(our merchant of record) and **credited to your organization's balance**. Your
first project also gets a **7-day trial credit**, so it is live right away.
After that each project costs $9 a month, charged daily from the balance (see
[Pricing and billing](https://docs.scribase.com/docs/pricing.md)).

## 3. Your backend is live

When you come back from checkout the console creates, without asking anything:

- your **organization**, named from your email (`ada@acme.io` becomes `acme`);
- your first **project**, `my-app`;
- its **`production`** environment: Postgres, Auth, Storage, Realtime (and
  Functions where the deployment runs them).

The **Your backend is live** screen shows the **Project URL** and the
**publishable key** with one-click copy, ready-to-paste setup for supabase-js,
Expo / React Native, Next.js and curl, and each service's status as it wakes.
You never create keys or secrets yourself.

```ts
import { createClient } from '@supabase/supabase-js'

export const supabase = createClient('<Project URL>', '<publishable key>')
```

For Expo put them in `.env` as `EXPO_PUBLIC_SUPABASE_URL` and
`EXPO_PUBLIC_SUPABASE_ANON_KEY`; for Next.js as `NEXT_PUBLIC_SUPABASE_URL` and
`NEXT_PUBLIC_SUPABASE_ANON_KEY`. The data plane is wire-compatible with
Supabase, so nothing else in your app changes.

## 4. Moving from Supabase? One field

Open **Move an existing Supabase project here** (or
[console.scribase.com/move](https://console.scribase.com/move)) and paste the
database connection string from Supabase dashboard > **Connect**. The move
starts on paste and shows its progress: tables, rows, users (with their
password hashes, so they keep signing in) and row-level security policies. To
copy storage files too, tick **Also copy storage files** and add the source
project's `service_role` key. Your Supabase project is only read.

When it finishes, the console shows the two values to switch your app to
(`SUPABASE_URL`, `SUPABASE_ANON_KEY`); from a terminal,
`scribase apps switch <org> <project>` prints the same for Expo.

## Pricing and limits

There is no project limit. Each project costs **$9 a month**, charged daily
($9 / 30 per project per day) from your organization's prepaid balance, or
the **Unlimited** plan covers any number of projects for **$299 a month**. Idle
projects scale to zero. The console's **Billing** page shows your balance,
"N projects × $9/mo", every daily charge, a **Top up** button and the
**auto top-up** setting. Details, including what happens when the balance runs
out, are in [Pricing and billing](https://docs.scribase.com/docs/pricing.md) and on
[scribase.com/pricing](https://scribase.com/pricing).

## Manage it from code (optional)

Everything above is also available over the `/v1` API, the SDK and the CLI.

| You need | Value |
|---|---|
| Control API (`SCRIBASE_API_URL`) | `https://api.scribase.com` |
| Credential (`SCRIBASE_ACCESS_TOKEN`) | A personal access token or organization API key, created below |

The examples below use organization `acme`, project `store` and environment
`production`; use the identifiers the console shows for yours.

### Create an access token

In the console, open **Account → Access tokens** and create a token. Copy it
when it is shown — the secret is displayed once and stored only as a hash.

For CI and services, prefer an **organization API key** (**Organization → API
tokens**) scoped to what the job needs: `read`, `deploy`, or `admin`.

Both are also available over the API; see
[Access tokens & API keys](https://docs.scribase.com/docs/api/tokens.md).

```sh
export SCRIBASE_API_URL=https://api.scribase.com
export SCRIBASE_ACCESS_TOKEN=scb_pat_...   # the token you just copied
```

### Make your first call

With plain HTTP:

```sh
curl -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  "$SCRIBASE_API_URL/v1/environments?organization_id=acme"
```

With the SDK (`scribase` on npm is not yet published; see [SDK installation](https://docs.scribase.com/docs/sdk.md#installation) for installing it from the repository):

```ts
import { ScribaseClient } from 'scribase';

const scribase = new ScribaseClient({
  baseUrl: process.env.SCRIBASE_API_URL ?? 'https://api.scribase.com',
  token: process.env.SCRIBASE_ACCESS_TOKEN ?? '',
});

const environments = await scribase.environments.list({ organizationId: 'acme' });
console.log(environments.map((env) => `${env.environment_id}: ${env.phase}`));
```

With the CLI (see [installation](https://docs.scribase.com/docs/getting-started.md)):

```sh
scribase doctor                          # checks the URL and token
scribase env get acme store production
```

### Create a preview for a pull request

```sh
# env create <org> <project> <env> <kind> <data-mode> <region> <idempotency-key> [ttl-hours]
scribase env create acme store pr-42 preview sanitized us-east create-pr-42 72
scribase operation get acme <operation-id-from-the-response>
scribase branch register acme store pr-42 --base production
```

The preview is swept automatically when its TTL expires. Renew it with
`POST .../environments/pr-42/renew` or `scribase.previews.renew(...)`.

### Apply migrations

```sh
scribase migrate acme store pr-42 --dir ./migrations          # plan and lint only
scribase migrate acme store pr-42 --dir ./migrations --apply  # run them
```

## Next steps

- [SDK reference](https://docs.scribase.com/docs/sdk.md) — every resource with examples
- [Backups & restore](https://docs.scribase.com/docs/api/backups.md) — verified backups and restore drills
- [Exports](https://docs.scribase.com/docs/api/exports.md) — take the whole stack with you
- [Import from Supabase](https://docs.scribase.com/docs/cli/import.md) — move an existing project in

---

Source: https://docs.scribase.com/docs/frameworks

# Frameworks

`npx scribase init` detects four project types from `package.json` and config
files, in this order:

| Detected as | When | Env file | Variables | Client file |
|---|---|---|---|---|
| `next` | `next` dependency or `next.config.*` | `.env.local` | `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` | `lib/supabase.ts` (`src/lib/` with a `src/` folder) |
| `expo` | `expo` dependency, or `app.json` plus `react-native` | `.env` | `EXPO_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_ANON_KEY` | `lib/supabase.ts` (`src/lib/` with a `src/` folder) |
| `vite` | `vite` dependency or `vite.config.*` | `.env.local` | `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY` | `src/lib/supabase.ts` |
| `node` | anything else | `.env` | `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` | `supabase.ts`, or `supabase.mjs` without `tsconfig.json` (under `src/` when it exists) |

Every run also writes `SCRIBASE_API_URL`, `SCRIBASE_ORG`, `SCRIBASE_PROJECT`
and `SCRIBASE_ENV`, adds the env file and `.scribase/` to `.gitignore`, and
installs `@supabase/supabase-js` with your package manager. Expo and Vite
projects never get the service role key, because their env values can end up
in the client bundle. The client file uses `.js` instead of `.ts` without a
`tsconfig.json`. An existing client file is kept.

## Per framework

| Framework | Detected as | Works as written? | The one edit |
|---|---|---|---|
| [Next.js](https://scribase.com/frameworks/nextjs) | `next` | Yes | None |
| [Expo](https://scribase.com/frameworks/expo) | `expo` | Yes | Optional: pass `AsyncStorage` as `auth.storage` to keep sessions |
| [React Native (bare CLI)](https://scribase.com/frameworks/react-native) | `expo` | Needs one edit | Metro without Expo does not inline `EXPO_PUBLIC_` values: put the URL and publishable key in `lib/supabase.ts` as constants |
| [Vite + React](https://scribase.com/frameworks/vite-react) | `vite` | Yes | None |
| [SvelteKit](https://scribase.com/frameworks/sveltekit) | `vite` | Yes | None; import as `$lib/supabase` |
| [Nuxt](https://scribase.com/frameworks/nuxt) | `node` | Needs one edit | Expose the pair through `runtimeConfig.public` and create the client in a composable |
| [Astro](https://scribase.com/frameworks/astro) | `node` | Needs one edit | Read `import.meta.env.SUPABASE_URL` instead of `process.env` |
| [Remix / React Router](https://scribase.com/frameworks/remix) | `vite` | Yes | Optional: move the client under `app/lib/` |
| [Node.js / Express](https://scribase.com/frameworks/express) | `node` | Yes | Start with `node --env-file=.env` |
| [Flutter](https://scribase.com/frameworks/flutter) | not supported | Manual | Use `supabase_flutter` with the URL and publishable key from the console, passed with `--dart-define` |

Each linked guide shows the real terminal output, the env file, a first
query and a prompt to paste into your coding agent.

## For coding agents

Run `npx scribase init --yes --json` in the project root. On success it prints
one JSON object with `framework`, `env_file`, `env_vars`, `client_file` and
`api_url`. If nobody is signed in it returns
`{"ok":false,"error":{"code":"authorization_pending",...}}` with a
`verification_uri_complete` and `user_code`: show those to the person, wait
for approval, and run the same command again. Never print the env file.

After init, create tables with the MCP server or migrations (see
[Connect your agent](https://docs.scribase.com/docs/agents/setup.md)), keep row-level security on for
every table the publishable key can reach, and use the service role key only
in server code.

---

Source: https://docs.scribase.com/docs/pricing

# Pricing and billing

Scribase has **no project limit**. You pay for the projects that exist:

| Option | Price | What it covers |
|---|---|---|
| **Per project** (default) | **$9 per project per month** | Postgres, Auth, Storage, Realtime, Functions and previews for each project |
| **Unlimited** | **$299 per month** | Any number of projects, under pooled fair-use quotas |

Idle projects scale to zero and wake on the next request; they are not paused
while your balance covers them. Self-hosting Scribase is free (Apache-2.0).

## How the balance works

1. **Sign up and a $1 card check.** A one-time $1 payment through Creem (our
   merchant of record) verifies your card and is credited 1:1 to your
   organization's balance.
2. **Trial credit.** After the card check your first project gets a **7-day
   trial credit**, so it is live immediately.
3. **Daily charges.** Once a day, every project that exists (running or
   scaled to zero) is charged **price / 30** from the balance: $0.30 a day at
   $9/month. Each project is charged at most once per day, so a retry never
   double-charges. On Unlimited the organization is charged $299 / 30 per day
   instead, whatever the project count. Delete a project and its charges stop
   from the next day.
4. **Top-ups.** **Top up** in Billing opens a one-click checkout for the amount
   you choose; the amount is credited as soon as the payment completes.
5. **Auto top-up.** Turn it on in Billing with a threshold and an amount. When
   the balance drops below the threshold, the console shows a one-click
   checkout for that amount. Creem cannot charge a saved card off-session for
   one-time payments, so **auto top-up is a prompted one-click checkout, not an
   automatic charge**: nothing is charged until you click it.
6. **Grace period, then pause.** If the balance reaches zero, projects keep
   running for **72 hours**. After that they **pause**: compute scales to zero
   and all data is kept. New projects cannot be created while paused.
7. **Resume.** A top-up that brings the balance above zero resumes paused
   projects right away.

The console **Billing** page shows the balance, "N projects × $9/mo = $X", a
per-project ledger of daily charges, the **Top up** button and the
**auto top-up** toggle. When the per-project total would be more than $299, it
suggests switching to Unlimited and shows how much you would save.

## Temporary agent projects

An agent can create a temporary project with `POST /v1/temporary-projects`
(see [Temporary databases](https://docs.scribase.com/docs/agents/temporary-databases.md)). Temporary
projects are **free for 72 hours**. Claim one to keep it; billing starts from
the claim. An unclaimed temporary project is removed when it expires.

## Unlimited fair use

Unlimited quotas are pooled across the organization, per calendar month:

| Resource | Fair use |
|---|---|
| Database | 500 GB |
| File storage | 2 TB |
| Egress | 5 TB |
| Compute hours | 50,000 |

Each environment still has its own hard caps (from `config/plans.json`), and
capacity packs add room to one environment.

## API

All routes are under `/v1/organizations/{org}/` and use the same bearer as the
rest of the API.

| Route | Who | What |
|---|---|---|
| `GET billing/balance` | Any member | Balance, price, billable projects, monthly estimate, status (active, grace, paused), auto top-up settings, pending top-up prompt, Unlimited savings |
| `GET billing/ledger` | Any member | Credits and daily charges, per project |
| `POST billing/top-up` | Owner, admin | `{"amount_cents":2000,"success_url":"https://..."}` returns a `checkout_url` |
| `POST billing/top-up-confirm` | Any member | `{"query":"..."}` from the signed success redirect; idempotent |
| `PUT billing/settings` | Owner, admin | Auto top-up (`auto_top_up_enabled`, `auto_top_up_threshold_cents`, `auto_top_up_amount_cents`) and `billing_model` (`per_project` or `unlimited`) |

## Operator configuration

Hosted billing is configured with environment variables on the control API.

| Variable | Default | Meaning |
|---|---|---|
| `SCRIBASE_PRICE_PER_PROJECT_CENTS` | `900` | Monthly price of one project; charged daily at price / 30 |
| `SCRIBASE_UNLIMITED_PLAN_CENTS` | `29900` | Monthly price of the Unlimited plan; charged daily at price / 30 |
| `SCRIBASE_TRIAL_DAYS` | `7` | Days of trial credit for the first project after the card check |
| `SCRIBASE_BILLING_GRACE_HOURS` | `72` | Hours projects keep running after the balance reaches zero |
| `SCRIBASE_TOP_UP_MIN_CENTS` | `500` | Smallest top-up |
| `SCRIBASE_TOP_UP_MAX_CENTS` | `100000` | Largest top-up |
| `CREEM_PRODUCT_ID_TOP_UP` | the card-check product | A $1 one-time Creem product; a top-up buys it in units. Falls back to `CREEM_PRODUCT_ID_CARD_CHECK` |
| `SCRIBASE_PROJECT_BILLING` | on when `CREEM_API_KEY` is set | `1`/`0` forces per-project billing on or off |
| `SCRIBASE_BILLING_SWEEP_SECONDS` | `300` | How often the daily-charge, pause and resume sweep runs |

The card check itself keeps its existing variables (`CREEM_API_KEY`,
`CREEM_PRODUCT_ID_CARD_CHECK`, `SCRIBASE_CARD_CHECK_CENTS`,
`SCRIBASE_REQUIRE_CARD`), and top-up payments arrive through the same signed
webhook (`CREEM_WEBHOOK_SECRET`). There is no project cap to configure; a
self-hosted deployment without billing never charges or pauses anything.

---

Source: https://docs.scribase.com/docs/getting-started

# Getting Started with Scribase

Scribase is an open application cloud built on PostgreSQL. It provides a
durable control plane, branching data environments, and a full set of
application-layer services — auth, storage, realtime subscriptions, and edge
functions — all deployable as a single stack that you own.

## What Scribase gives you

| Surface | Description |
|---|---|
| Control-plane API | Durable `/v1` REST API for organizations, projects, environments, and operations |
| Local dev | `scribase dev` — Postgres + all services, no Docker, no configuration |
| Branching | Schema-level CoW branches for each pull request or preview environment |
| Migrations | Lint-first migration runner with up/down tracking |
| Auth | JWT-based authentication with OAuth providers via GoTrue |
| Storage | S3-compatible object storage with bucket policies |
| Realtime | WebSocket subscriptions over Postgres replication |
| Functions | V8-based edge function runtime |
| Aegis | Compile-time RLS policy verifier |
| SDK | Typed TypeScript client — `scribase` on npm |

There are two ways in:

- **Hosted Scribase** — sign up, add a card ($1, credited back), and your
  backend is live with its URL and key in about a minute. Nothing to install.
  Follow the [hosted quickstart](https://docs.scribase.com/docs/hosted.md).
- **Local development** — run the whole stack on your machine with the
  `scribase` CLI, below.

## Quick start (local development)

### 1. Install the CLI and its prerequisites

The CLI is a single Rust binary named `scribase`. Build it from a checkout of the
Scribase source with Rust 1.85 or newer:

```sh
cargo install --locked --path crates/scribase-cli
scribase version
```

The source repository is private while Scribase is in early access; email
[hello@scribase.com](mailto:hello@scribase.com) for access. If you only need the
hosted platform, skip the CLI and use the [SDK](https://docs.scribase.com/docs/sdk.md) instead.

Local databases use your installed PostgreSQL 17 server binaries (`initdb` and
`pg_ctl` must be on `PATH` — for example `brew install postgresql@17` on macOS or
the `postgresql-17` package on Debian/Ubuntu). The optional application services
are the upstream open-source binaries — `gotrue` (auth), `storage-api`
(storage), `realtime`, and `edge-runtime` (functions) — found next to the
`scribase` binary or on `PATH`. A missing service is skipped with a message;
the database always comes up.

```sh
# Check your API configuration once you have a token (optional for local work)
scribase doctor
```

### 2. Start the local stack

From your project directory, start the full local stack — Postgres, auth,
storage, realtime, and functions — with one command. No Docker and no
configuration file are required for the database; service binaries are resolved
from the same directory as the `scribase` binary or from `PATH`.

```sh
scribase dev
```

Scribase boots Postgres locally, runs bootstrap migrations, then brings up the
application services. The process blocks and prints connection information:

```
preflight: service binaries
  auth       found    /usr/local/bin/gotrue
  storage    found    /usr/local/bin/storage-api
  realtime   found    /usr/local/bin/realtime
  functions  found    /usr/local/bin/edge-runtime
database ready at .scribase
```

To start only specific services:

```sh
scribase dev --services auth,storage
```

### 3. Apply a schema

```sh
scribase dev up --schema schema.scribase
```

The schema file uses the Scribase schema language — a typed model definition
that compiles to Postgres DDL with row-level security policies baked in. See
[Aegis Policy Compiler](https://docs.scribase.com/docs/aegis.md) for the policy syntax.

### 4. Connect

`scribase dev url` prints the connection string for the primary database:

```sh
psql "$(scribase dev url)"
```

### 5. Branch for a feature

```sh
scribase branch new my-feature
# returns the branch connection string
```

Scribase uses copy-on-write snapshots to create branches in under a second.
Each branch is an independent Postgres cluster under `.scribase/`.

## Next steps

- [Hosted quickstart](https://docs.scribase.com/docs/hosted.md) — sign up, create a token, make your first API call
- [Self-hosting on a server](https://docs.scribase.com/docs/self-hosting.md) — Docker Compose or Helm
- [CLI reference](https://docs.scribase.com/docs/cli.md) — all commands and flags
- [Control API](https://docs.scribase.com/docs/api.md) — the `/v1` REST interface
- [SDK](https://docs.scribase.com/docs/sdk.md) — the `scribase` TypeScript client
- [Concepts](https://docs.scribase.com/docs/concepts/branching.md) — branching, auth, storage, realtime

## Configuration

The local stack resolves configuration from environment variables.

| Variable | Purpose |
|---|---|
| `SCRIBASE_HOME` | Override the `.scribase` workspace directory |
| `SCRIBASE_API_URL` | Control-plane API the CLI talks to — `https://api.scribase.com` for hosted Scribase |
| `SCRIBASE_ACCESS_TOKEN` | Personal access token or organization API key ([how to create one](https://docs.scribase.com/docs/api/tokens.md)) |
| `SCRIBASE_CURL_BINARY` | Override the `curl` binary used by the CLI |

---

Source: https://docs.scribase.com/docs/self-hosting

# Self-hosting Scribase

Scribase ships two first-class deploy targets under `deploy/`:

| Target | Path | Use it for |
|---|---|---|
| Docker Compose | `deploy/compose/` | Single-box deployments — one host, all services |
| Helm chart | `deploy/helm/scribase/` | Kubernetes — control plane and optional shared data plane |

Hosting many small projects (one per app) on one VPS? Use the
[single-box layout](https://docs.scribase.com/docs/single-box.md) instead: scale-to-zero project containers,
shared storage, realtime and functions, and built-in admin sign-in.

The service stack is the same in both: **postgres · control-api · gateway (Envoy) · auth · rest · storage · realtime · functions · worker**. Background jobs (backups, restores, verifications, exports, scheduled backups, retention, export expiry and usage metering) run inside `control-api` as its data-job workers, so there is no separate scheduler service.

---

## What you must provide

Everything else has a working default. These four are yours to supply:

1. **A PostgreSQL 17 database.** Compose runs one for you (`supabase/postgres`); a production install points at your own managed database. The schema migrator needs a role with `BYPASSRLS`; the API and operator use least-privilege login roles.
2. **A public domain** — where clients reach the gateway, e.g. `scribase.example.com`.
3. **A TLS certificate** for that domain. The gateway speaks plain HTTP internally and trusts a TLS terminator in front of it.
4. **Operator sign-in** for the management API: either the control plane's own password login (`SCRIBASE_AUTH_MODE=builtin`, no identity provider needed; see [Built-in admin login](https://docs.scribase.com/docs/admin-login.md)), or an OIDC provider with token introspection (`SCRIBASE_AUTH_MODE=oidc` + `SCRIBASE_OIDC_*`). If you provision managed per-tenant databases via Neon, also a **Neon API key** (`SCRIBASE_NEON_API_KEY`).

Secrets are never baked into images or committed. Generate them, then pass them via `.env` (Compose) or a Kubernetes Secret / external secret store (Helm).

---

## Single-box deploy (Docker Compose)

Files: `deploy/compose/docker-compose.yml`, `.env.example`, `envoy/envoy.yaml`, `initdb/`.

### 1. Configure

```sh
cd scribase/deploy/compose
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD, JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY,
# SECRET_KEY_BASE, and either SCRIBASE_AUTH_MODE=builtin or the
# SCRIBASE_OIDC_* values. See the file comments.
```

Required secrets to generate:

```sh
# JWT secret (at least 32 random bytes, base64-encoded)
openssl rand -base64 32

# Anon key and service-role key are JWTs signed with JWT_SECRET.
# Generate them with the scribase CLI or the Scribase Console.
```

### 2. Validate the config (no daemon required)

```sh
docker compose --env-file .env -f docker-compose.yml config
```

### 3. Boot

```sh
docker compose --env-file .env -f docker-compose.yml up -d --build
```

Boot order is enforced by health and completion gates:

1. `db` becomes healthy
2. `migrate` (one-shot) applies `postgres/migrations/*.sql` and exits `0`
3. `control-api`, `auth`, `rest`, `storage`, `realtime`, `functions` start
4. `gateway` (Envoy) starts once all data-plane services are up

### 4. Verify

```sh
# Public API through the gateway
curl http://localhost:8000/health/ready

# Management API directly
curl http://localhost:8081/health/ready
```

### 5. Register your first organization

```sh
export SCRIBASE_API_URL=http://localhost:8081
# builtin mode: the first run creates the administrator and signs in;
# later runs use `scribase login --email you@example.com`.
scribase admin setup --email you@example.com --setup-token scb_setup_...
# oidc mode instead: export SCRIBASE_ACCESS_TOKEN=<token from your identity provider>

scribase doctor
scribase org put myorg "My Organization"
scribase project put myorg myproject aws-us-east-1
scribase env create myorg myproject production production snapshot aws-us-east-1 init-001
scribase operation get myorg <operation-id>
```

---

## Kubernetes deploy (Helm)

The Helm chart at `deploy/helm/scribase/` manages the control-plane components and its PostgreSQL dependency.

### Prerequisites

- Helm 3.x
- A Kubernetes cluster (1.28+)
- A PostgreSQL 17 database accessible from the cluster
- A TLS-terminating Ingress controller

### 1. Add values

```sh
cp deploy/helm/scribase/values.yaml myvalues.yaml
# Edit myvalues.yaml
```

Key values to set:

```yaml
controlApi:
  database:
    url: "postgresql://scribase_api:PASSWORD@postgres:5432/scribase?sslmode=require"
  oidc:
    introspectionEndpoint: "https://idp.example.com/oauth/introspect"
    issuer: "https://idp.example.com"
    audience: "scribase-api"
    clientId: "scribase-control"
    clientSecret: "SECRET"

gateway:
  domain: "scribase.example.com"

secrets:
  jwtSecret: "GENERATED_JWT_SECRET"
  anonKey: "GENERATED_ANON_JWT"
  serviceRoleKey: "GENERATED_SERVICE_ROLE_JWT"
```

### 2. Install

```sh
helm install scribase deploy/helm/scribase/ -f myvalues.yaml -n scribase --create-namespace
```

### 3. Upgrade

```sh
helm upgrade scribase deploy/helm/scribase/ -f myvalues.yaml -n scribase
```

### 4. Scale

```sh
kubectl scale deployment scribase-control-api --replicas=3 -n scribase
```

---

## Environment variables reference

### Control API

| Variable | Required | Description |
|---|---|---|
| `SCRIBASE_API_DATABASE_URL` | Yes | TLS URL for the `scribase_api` role |
| `SCRIBASE_AUTH_MODE` | No | `oidc` (default here) or `builtin` |
| `SCRIBASE_ADMIN_EMAIL`, `SCRIBASE_ADMIN_PASSWORD_HASH` | No | builtin only: pre-seed the first administrator |
| `SCRIBASE_OIDC_INTROSPECTION_ENDPOINT` | oidc only | RFC 7662 token introspection HTTPS endpoint |
| `SCRIBASE_OIDC_ISSUER` | oidc only | Exact trusted `iss` claim |
| `SCRIBASE_OIDC_AUDIENCE` | oidc only | Required `aud` claim |
| `SCRIBASE_OIDC_CLIENT_ID` | oidc only | Introspection client ID |
| `SCRIBASE_OIDC_CLIENT_SECRET` | oidc only | Introspection client secret |
| `SCRIBASE_HTTP_BIND` | No | Default `127.0.0.1:8080` |
| `SCRIBASE_TRUST_PROXY_TLS` | No | Set to `1` to allow non-loopback bind |
| `SCRIBASE_MAX_ENVIRONMENTS` | No | Default `10` per new organization |
| `SCRIBASE_DATABASE_MAX_CONNECTIONS` | No | Default `10` |

### Organization single sign-on (optional)

Needed only if organizations will connect their own identity provider (see
[Single sign-on](https://docs.scribase.com/docs/concepts/sso.md)). Apply control-plane migration `0018`
first.

| Variable | Description |
|---|---|
| `SCRIBASE_PUBLIC_API_URL` | Public `https://` origin of the control API. Used for the OIDC redirect URI and the SAML entity ID and ACS URL. SSO is unavailable until it is set. |
| `SCRIBASE_CONSOLE_URL` | Console origin the browser returns to after the IdP. Default `https://console.scribase.com`. |
| `SCRIBASE_KMS_MASTER_KEY` | 64 hex characters. Seals OIDC client secrets at rest (shared with environment secrets). |
| `SCRIBASE_ORG_SETTINGS_DATABASE_URL` | Store for SSO settings, sign-in state and sessions; falls back to `SCRIBASE_CONTROL_PLANE_ADMIN_DATABASE_URL`. |
| `SCRIBASE_SSO_SESSION_HOURS` | Console session length after SSO, 1 to 168. Default `12`. |
| `SCRIBASE_DOH_URL` | DNS-over-HTTPS JSON endpoint for domain verification. Default Cloudflare's public resolver. |

### Neon integration (optional)

| Variable | Description |
|---|---|
| `SCRIBASE_NEON_API_KEY` | Neon API key for managed Neon environments |
| `SCRIBASE_NEON_PROJECT_REGION` | Default Neon region for new environments |

---

## Database roles

Scribase uses three database roles:

| Role | Privileges | Used by |
|---|---|---|
| `scribase_migrator` | `BYPASSRLS`, DDL | Schema migration runner |
| `scribase_api` | Least-privilege DML | control-api process |
| `scribase_operator` | Operator plans | Operator (`worker`) |

The `bootstrap.sql` script creates all three. The control-api process is never given the migrator or operator credential.

---

## Upgrading

1. Pull the new images or build from source.
2. Run the migration runner: `docker compose run --rm migrate`.
3. Restart services: `docker compose up -d`.

The migration runner is idempotent and checksum-guarded — it will not re-apply already-applied migrations.

---

Source: https://docs.scribase.com/docs/single-box

# Single-box deploy (many projects)

This layout hosts **30 to 50 small projects (for example one per mobile app or
game) on one VPS** in a 6 to 8 GB RAM budget. It is the layout Scribase itself
is operated on. For a plain one-tenant stack, see
[Self-hosting](https://docs.scribase.com/docs/self-hosting.md). The full operator reference, with memory
budgets and every overlay, is `DEPLOY.md` in the repository.

| File | Role |
|---|---|
| `deploy/compose/docker-compose.yml` | Base stack: control-plane Postgres, migrator, control API |
| `deploy/compose/docker-compose.single-box.yml` | Overlay: operator, activator, project router, restore-verify scratch database, memory caps |
| `deploy/compose/docker-compose.shared-services.yml` | One shared storage, realtime and edge-functions runtime for every project |
| `deploy/compose/docker-compose.postgres-cow.yml` | Default engine: one small Postgres 17 per environment on this box, branches as copy-on-write clones |
| `deploy/compose/docker-compose.neon-local.yml` | Optional: self-hosted Neon on the same box (instead of `postgres-cow`) |
| `deploy/compose/single-box.env.example` | Env template (variable names only, no values) |

## How it works

- **Every environment gets its own Postgres 17 on the box**
  (`SCRIBASE_DATA_ENGINE=postgres-cow`). A branch (preview, staging, a sandbox
  per agent session) is a copy-on-write clone of its parent's data directory:
  it takes milliseconds and only costs the blocks that later change. An idle
  environment's database is stopped after `SCRIBASE_POSTGRES_COW_SUSPEND_SECONDS`
  (default 900, like the API container) and started again by the next
  connection. The bundled `db` holds only the control plane. No cloud account
  is needed.
- **Managed Neon is optional.** Set `SCRIBASE_NEON_API_KEY` and new projects
  can use `neon-cloud` (one Neon project per Scribase project, 0.25 CU,
  suspended after 5 idle minutes, point-in-time restore). `scribase project
  move <org> <project> --engine postgres-cow|neon-cloud|neon-local` moves a
  project between engines and keeps its URL and keys.
- **One container per environment** runs GoTrue (`/auth/v1`) and PostgREST
  (`/rest/v1`). It **scales to zero**: the activator starts it on the first
  request and stops it after `SCRIBASE_PROJECT_IDLE_SECONDS` (default 900)
  without traffic. An idle project uses disk, not memory.
- **Storage, realtime and edge functions are shared**, multi-tenant services.
  Each function call runs in its own isolated Deno worker that only sees its
  environment's variables and secrets.
- **Every environment is served at `https://<host label>.<your domain>`**
  through the project router.
- **Operator sign-in is built in** (`SCRIBASE_AUTH_MODE=builtin`). No identity
  provider is needed. See [Built-in admin login](https://docs.scribase.com/docs/admin-login.md).

## 1. Build the images

```sh
sudo git clone <your scribase remote> /srv/src/scribase
cd /srv/src/scribase/deploy/compose

# Control-plane image (control API, operator, activator, CLI).
docker compose -f docker-compose.yml build migrate
# Per-environment runtime image (GoTrue + PostgREST).
docker compose -f docker-compose.yml -f docker-compose.single-box.yml \
  --profile build build project-runtime-image
```

## 2. Configure

```sh
sudo install -m 640 -o root -g deploy single-box.env.example /etc/products/scribase.env
sudoedit /etc/products/scribase.env
```

Fill every blank in the template:

- Control-plane passwords and keys (`openssl rand -hex 32` for each).
- `SCRIBASE_ORGANIZATION_ID`, the id of your first organization.
- `SCRIBASE_POSTGRES_COW_HOST_DIR` (default `/srv/scribase/pg-cow`): a
  directory on a filesystem that can clone files (XFS, btrfs or ZFS), owned by
  uid 10001, mode 0700. On an ext4 root, create an XFS image file and
  loop-mount it there (see [Copy-on-write storage](#copy-on-write-storage)).
- Optional: `SCRIBASE_NEON_API_KEY`, a Neon API key, to offer `neon-cloud` too.
- The `SHARED_*` keys for the shared storage and realtime services, and SMTP.
- `SCRIBASE_FUNCTIONS_ADMIN_KEY`, its own random value. The functions runtime
  refuses an admin key that equals a key functions can read.
- `SCRIBASE_RESTORE_VERIFY_DB_PASSWORD`, the password of the bundled
  `restore-verify-db` scratch server that Backup Verify restores into. Leave
  `SCRIBASE_RESTORE_VERIFY_DATABASE_URL` blank to use that server. Without a
  verification database, Backup Verify answers `503 verification_not_configured`.
- Leave `SCRIBASE_ADMIN_EMAIL` and `SCRIBASE_ADMIN_PASSWORD_HASH` blank to get a
  one-time setup token in the log, or pre-seed the administrator (see
  [Built-in admin login](https://docs.scribase.com/docs/admin-login.md)).

Keep every published port on `127.0.0.1`. Docker bypasses host firewalls such
as UFW.

## 3. DNS and TLS

- `api.<domain>` and `console.<domain>`: ordinary records pointing at the box.
- `*.<domain>`: one wildcard record to the box. Every environment is served at
  `https://<host label>.<domain>`.
- A wildcard certificate. HTTP-01 cannot issue one, so use DNS-01 or, behind
  Cloudflare, a Cloudflare Origin CA certificate for `*.<domain>, <domain>`
  with SSL mode "Full (strict)".
- Your TLS terminator forwards `api.` to `127.0.0.1:8081` and `*.` to
  `127.0.0.1:8010` (the project router).

## 4. Boot

```sh
cd /srv/src/scribase/deploy/compose
dc="docker compose -p scribase --env-file /etc/products/scribase.env \
  -f docker-compose.yml -f docker-compose.single-box.yml -f docker-compose.shared-services.yml \
  -f docker-compose.postgres-cow.yml"

$dc config -q      # validate first
$dc up -d
```

## 5. Create the administrator and the organization

Skip `admin setup` if you pre-seeded `SCRIBASE_ADMIN_*`, and sign in with
`scribase login --email ...` instead.

```sh
$dc logs control-api | grep -A1 'setup token'          # scb_setup_...
$dc exec -e SCRIBASE_API_URL=http://127.0.0.1:8080 control-api \
  scribase admin setup --email you@yourdomain --setup-token scb_setup_...
$dc exec -e SCRIBASE_API_URL=http://127.0.0.1:8080 control-api \
  scribase org put <SCRIBASE_ORGANIZATION_ID value> "Your Org"
```

You can also open the console: on a control plane with no administrator, its
sign-in page asks for the setup token instead of a password.

## 6. First project

Create a project and a `production` environment in the console, or with the
CLI (see [Organizations, projects and environments](https://docs.scribase.com/docs/cli/resources.md)):

```sh
scribase project put <org> my-app aws-eu-central-1
scribase env create <org> my-app production production snapshot aws-eu-central-1 first-env-1
```

The operator creates the environment's database, bootstraps the Supabase
roles, publishes the runtime and creates the project container. Then check it with the
host label and `anon` key the console shows on the environment's API keys page:

```sh
host=https://<label>.<domain>
curl -fsS "$host/auth/v1/health"                          # starts the container
curl -fsS "$host/rest/v1/" -H "apikey: $ANON" -H "Authorization: Bearer $ANON"
```

Point an app at it with [`scribase apps switch`](https://docs.scribase.com/docs/cli/apps.md) and generate
its types with [`scribase gen types`](https://docs.scribase.com/docs/cli/gen-types.md).

## Backups on the single box

Backups, verification restores and scheduled restore drills run inside the
control API. Verification restores into the bundled `restore-verify-db` scratch
server and never touches `db` or a project's own database. Check it after boot:

```sh
$dc exec restore-verify-db pg_isready -U postgres -h localhost
```

A restore into an environment that already has data lands in a new
`restore_<id>` database. Switching the environment to it (console: restore
history, **Switch**) recreates the project container on the restored database.
See [Backups and restore](https://docs.scribase.com/docs/cli/backup.md).

## Limits to know

- The control API caps environments at `SCRIBASE_MAX_ENVIRONMENTS` (60 by
  default on this layout). On `neon-cloud`, your Neon plan's project limit also
  applies.
- A cold request pays the container start (measured 0.7 s to healthy) plus the
  database start (well under a second for `postgres-cow`; typically 0.5 to 1 s
  for a Neon compute).
- `postgres-cow` restores to a backup or to the head of the parent branch; it
  has no point-in-time restore to an arbitrary timestamp (use `neon-cloud` for
  that). Cutting a branch from a running environment pauses that environment's
  database for the length of the clone (milliseconds).
- An engine move (`scribase project move`) pauses writes for the duration of
  the copy.

## Copy-on-write storage

`postgres-cow` refuses to start on a filesystem that cannot clone files,
because every branch would silently become a full copy. Most VPS images boot
from ext4, so give the engine an XFS filesystem inside an image file:

```sh
sudo apt-get install -y xfsprogs
sudo fallocate -l 30G /srv/scribase-pg-cow.xfs
sudo mkfs.xfs -m reflink=1 /srv/scribase-pg-cow.xfs
sudo install -d -m 700 /srv/scribase/pg-cow
echo '/srv/scribase-pg-cow.xfs /srv/scribase/pg-cow xfs loop,noatime,nofail 0 0' | sudo tee -a /etc/fstab
sudo mount /srv/scribase/pg-cow
sudo chown 10001:10001 /srv/scribase/pg-cow && sudo chmod 700 /srv/scribase/pg-cow
```

Check it from the worker: `$dc exec worker scribase-postgres-cow status`.

---

Source: https://docs.scribase.com/docs/admin-login

# Built-in admin login

A self-hosted control plane can verify operators in one of two ways, selected
by `SCRIBASE_AUTH_MODE`:

| Mode | What signs you in | Default on |
|---|---|---|
| `builtin` | The control plane's own password login (argon2id, optional TOTP) | The [single-box layout](https://docs.scribase.com/docs/single-box.md) |
| `oidc` | An external identity provider with RFC 7662 token introspection (`SCRIBASE_OIDC_*`) | Everything else |

Personal access tokens, organization API keys and organization SSO sessions
work in both modes. This page covers `builtin`.

## Create the first administrator

Pick one of two options.

**Option A: setup token (no secret in the env file).** Leave
`SCRIBASE_ADMIN_EMAIL` and `SCRIBASE_ADMIN_PASSWORD_HASH` blank. While no
administrator exists, every boot prints a one-time setup token to the
control-API log. Spend it from the CLI:

```sh
docker compose -p scribase logs control-api | grep -A1 'setup token'
scribase admin setup --email you@example.com --setup-token scb_setup_...
```

or open the console: its sign-in page shows a **Setup token** form instead of
the password form until an administrator exists. Setting only
`SCRIBASE_ADMIN_EMAIL` binds the token to that address.

**Option B: pre-seed the administrator.** Generate a password hash and put it
in the env file:

```sh
scribase admin hash-password        # prompts twice, prints an argon2id PHC string
```

```sh
SCRIBASE_ADMIN_EMAIL=you@example.com
SCRIBASE_ADMIN_PASSWORD_HASH='$argon2id$v=19$m=19456,t=2,p=1$...'
```

Wrap the hash in **single quotes** so Docker Compose keeps every `$`. On boot
the account is created or promoted. Changing the hash later resets that
administrator's password once, on the next boot. That is the break-glass path
if you are locked out.

## Sign in

- **Console**: when the control plane can send email (see
  [Sign in with an email link](#sign-in-with-an-email-link)), the sign-in page
  leads with **Email me a sign-in link**; **Use a password instead** shows the
  password form. After either, an authentication code follows if the account
  has an authenticator app. **Use a recovery code instead** accepts one of the
  one-time recovery codes.
- **CLI**: `scribase login --email you@example.com` prompts for the password
  (echo off, never from arguments) and then for a code if one is enrolled. See
  [Login and tokens](https://docs.scribase.com/docs/cli/login.md).

## Security properties

- **Passwords**: argon2id (19 MiB, t=2), at least 12 characters. An unknown
  account and a wrong password answer the same `401` after the same work.
- **Lockout and rate limits**: 10 failed passwords within 15 minutes lock the
  account for 15 minutes (`SCRIBASE_LOGIN_MAX_FAILURES`,
  `SCRIBASE_LOGIN_LOCKOUT_SECONDS`). Each client address is also limited to 20
  sign-in attempts per 5 minutes.
- **Two-factor**: enroll an authenticator app under **Account > Security**.
  TOTP secrets are sealed with `SCRIBASE_KMS_MASTER_KEY`. Regenerate recovery
  codes on the same page.
- **Sessions**: opaque `scb_ses_` bearers, stored only as SHA-256 digests, with
  an idle timeout (default 2 hours), an absolute timeout (default 12 hours) and
  rotation every 15 minutes (`SCRIBASE_SESSION_IDLE_SECONDS`,
  `SCRIBASE_SESSION_ABSOLUTE_SECONDS`, `SCRIBASE_SESSION_ROTATE_SECONDS`). You can
  list and sign out sessions under **Account > Security > Sessions**.
- **Audit**: every sign-in, failure, lockout, sign-out and password change is
  recorded (`GET /v1/auth/builtin/events`, administrators only).

## Sign in with an email link

When email is configured (webhook or box SMTP, as above), members can sign in
without a password. They enter their email and get a message with a single-use
link and a 6-digit code (for signing in on another device). Both expire in
15 minutes; asking again replaces the earlier ones, and a code allows at most
5 guesses.

- The link opens `SCRIBASE_CONSOLE_URL/auth/magic?token=scb_mgl_...`, which
  only previews the link; the member clicks **Continue** to sign in, so mail
  scanners that open every URL cannot use it up.
- The answer to a request is the same whether or not the address has an
  account. Requests are limited to 5 per 5 minutes per client address and per
  email, plus one email per address per minute.
- A new address gets its account when the link is redeemed, if sign-up is open
  (`SCRIBASE_PUBLIC_SIGNUP`); the organization card check still applies before
  the first project.
- The operator administrator never gets a link: a request for that address
  sends a notice to sign in with the password and second factor instead.
- API: `POST /v1/auth/builtin/magic-link/request` `{"email"}`,
  `.../magic-link/preview` `{"token"}`, `.../magic-link/verify` `{"token"}` or
  `{"email","code"}`. Table: control-plane migration
  `0030_builtin_magic_links.sql`.

## Invite members

An organization owner or admin invites people by email from the console. The
invitee opens the link, sets a password and joins with the invited role. The
normal organization roles (owner, admin, developer, viewer) apply.

## Reset a forgotten password

Reset links are single use and stored only as SHA-256 digests. Creating a new
link replaces the account's earlier unused ones. Setting the new password
clears any lockout and signs out every session of the account. It does not
sign the member in: they sign in normally afterwards, so an authenticator app
still applies.

- **Administrator-issued (always available)**: under **Account > Security >
  Reset a member's password**, the operator administrator enters the member's
  email and their own password, and gets a link valid for 24 hours to share.
  API: `POST /v1/auth/builtin/password-resets` with
  `{"email", "admin_password"}`.
- **Emailed (when a mail relay is configured)**: set
  `SCRIBASE_MAIL_WEBHOOK_URL` to an `https://` relay that accepts
  `{to, subject, text, html}` JSON (bearer `SCRIBASE_MAIL_WEBHOOK_TOKEN`), the
  same relay that emails invitations. The sign-in page then offers **Forgot your
  password?**, which emails a link valid for 1 hour. The answer is the same
  whether or not the email has an account, and each address gets at most one
  email per minute. Without a relay, the page tells the member to ask the
  administrator. Instead of a webhook you can use the box SMTP relay: when
  `SCRIBASE_MAIL_WEBHOOK_URL` is unset and `SCRIBASE_DEFAULT_SMTP_HOST` plus
  `SCRIBASE_DEFAULT_SMTP_ADMIN_EMAIL` are set (the single-box compose passes
  them from `SMTP_*` in `.env`), account email goes out over SMTP (port 465
  implicit TLS, any other port STARTTLS, required).

Links open `SCRIBASE_CONSOLE_URL/reset-password/<token>`, so set
`SCRIBASE_CONSOLE_URL` on the control API. The reset table comes from
control-plane migration `0023_builtin_password_resets.sql`.

The administrator cannot create a link for their own account. If the
administrator is locked out, set a new `SCRIBASE_ADMIN_PASSWORD_HASH` and
restart (see above).

## Console configuration

Build the console with `SCRIBASE_AUTH_MODE=builtin` and give its server
`SCRIBASE_API_INTERNAL_URL` (for example `http://127.0.0.1:8081`). The console
server keeps the session in a `__Host-` cookie (`HttpOnly`, `Secure`,
`SameSite=Lax`) and proxies `/v1` calls, checking origin and a CSRF token on
every mutation. The bearer never reaches browser script. Set
`SCRIBASE_CONSOLE_URL` to the console's public origin. For plain-HTTP local
development only, set `SCRIBASE_CONSOLE_INSECURE_COOKIES=1`.

## Automation

A CLI session ends with the timeouts above. For CI and scripts, create a
personal access token with `scribase token create` or an organization API key
(see [Access tokens & API keys](https://docs.scribase.com/docs/api/tokens.md)).

---

Source: https://docs.scribase.com/docs/agents

# Build with AI agents

Scribase is built to be driven by a coding agent. The agent creates the
project, writes migrations with row level security, wires auth and storage,
deploys functions and works on its own branch, through the same `/v1` API
the console uses. You approve the parts that touch production.

## The 60-second path

**1. Once: sign up.** Sign up at
[console.scribase.com/signup](https://console.scribase.com/signup) (Google,
GitHub or email, then the one-time $1 card check, which is credited to your
balance). You never copy a secret key into the agent: it signs in by itself
and you approve it in the browser (see
[Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md)).

**2. Once: connect your agent.** Claude Code:

```sh
claude mcp add --transport http scribase https://api.scribase.com/mcp
```

Claude Code opens the Scribase consent page the first time it connects. For
the CLI, the agent runs `scribase login` and shows you a link and a code to
approve.

Cursor, Codex, Windsurf and the local server: [Connect your agent](https://docs.scribase.com/docs/agents/setup.md).

**3. Ask.** For example:

> Create a Scribase project called `my-app`, write its URL and anon key to
> `.env`, and add a `todos` table that each user can only see their own rows of.

The agent calls `org.list`, `project.put` and `environment.create`, polls
`operation.get` until the database is live, writes `.env` with the URL and
the anon key (never the service key) using
`scribase apps switch <org> my-app --format dotenv`, writes
`supabase/migrations/001_todos.sql` with RLS policies, and applies it with
`migrate.run`. Each mutating tool call carries `confirm: true`, which your
agent client shows you before it runs.

The key step uses the CLI today (see [Connect your agent](https://docs.scribase.com/docs/agents/setup.md#the-cli-for-agents-that-prefer-a-shell));
an MCP tool that returns an environment's public URL and key is coming.

## Teach your agent Scribase

Give the agent the rules and recipes, so it does not have to guess:

| Agent | Add to your project |
|---|---|
| Claude Code | The `scribase` plugin (skills + MCP), or `.claude/skills/scribase/` and a `CLAUDE.md` section |
| Codex and most others | An `AGENTS.md` section |
| Cursor | `.cursor/rules/scribase.mdc` |
| Windsurf | `.windsurf/rules/scribase.md` |

All of these live in the `agents/` folder of the Scribase repository and
say the same thing: never ask you for keys (sign in with `scribase login`
instead), keep keys out of output and git, schema changes only
through migrations, RLS on every table, a preview branch per task, and no
production merge, delete or key rotation without your explicit approval.

Any agent can also read the whole documentation as plain text:
[/llms.txt](https://docs.scribase.com/llms.txt) (an index) and
[/llms-full.txt](https://docs.scribase.com/llms-full.txt) (everything). Every
page is available as markdown by adding `.md` to its URL, for example
[/docs/agents.md](https://docs.scribase.com/docs/agents.md).

## What the agent can do

| Area | MCP tools | CLI |
|---|---|---|
| Projects and environments | `project.put`, `environment.create`, `environment.list`, `operation.get` | `scribase project put`, `scribase env create` |
| Keys into `.env` | (CLI) | `scribase apps switch <org> <project> --format dotenv` |
| Schema and RLS | `migrate.run`, `policy.test`, `schema.apply`, `database.tables` | `scribase migrate --dir`, `scribase db pull`, `scribase gen types` |
| Branch per task | `environment.create` (preview), `branch.register`, `branch.diff`, `branch.merge` | `scribase branch` |
| Functions | `functions.list`, `logs.tail` | `scribase functions deploy`, `scribase secrets set` |
| Inspect | `database.query` (read-only), `auth.users`, `storage.buckets`, `insights.get`, `usage.get` | `scribase insights` |
| Move from Supabase | `import.supabase`, `import.status` | `scribase import supabase` |
| Recover | `backup.create`, `backup.restore` | `scribase backup`, `scribase restore` |

## Next

- [Connect your agent](https://docs.scribase.com/docs/agents/setup.md): Claude Code, Cursor, Codex, Windsurf, local server
- [Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md): device login, MCP OAuth, paste-safe tokens
- [Tokens and safety](https://docs.scribase.com/docs/agents/safety.md): scopes, expiry, revocation, audit, confirm
- [Branch per task](https://docs.scribase.com/docs/agents/branch-per-task.md): previews an agent can break freely
- [Temporary databases](https://docs.scribase.com/docs/agents/temporary-databases.md): what exists today and what is coming

---

Source: https://docs.scribase.com/docs/agents/setup

# Connect your agent

Nobody pastes a secret key into the agent's chat. Pick one:

- **Browser sign-in (MCP OAuth).** Clients that support MCP authorization
  (Claude Code, Cursor, VS Code) open the Scribase consent page the first time
  they connect; add the server without a header.
- **`scribase login`.** The agent runs it, shows you a link and a code, and you
  approve in the browser; it receives its own scoped, expiring token and keeps
  it in the keychain. See [Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md).
- **An agent token in `SCRIBASE_ACCESS_TOKEN`**, for clients that need a
  header. See [Tokens and safety](https://docs.scribase.com/docs/agents/safety.md) for which token to give
  an agent. Keep it in your shell environment or secret manager, never in a
  committed file.

## Remote MCP server

The hosted MCP endpoint is `https://api.scribase.com/mcp` (streamable HTTP,
bearer token). There is nothing to install. Each session gets its own scratch
database for the schema tools, destroyed when the session ends, so one
agent's experiments never reach another's.

### Claude Code

```sh
claude mcp add --transport http scribase https://api.scribase.com/mcp
```

Claude Code opens the Scribase consent page in your browser the first time it
connects. With a token instead:

```sh
claude mcp add --transport http scribase https://api.scribase.com/mcp \
  --header "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN"
```

Or install the Scribase plugin, which bundles the MCP server with the
`scribase` and `scribase-safe-change` skills. From a checkout of the Scribase
repository:

```sh
claude plugin marketplace add ./agents/plugin
claude plugin install scribase@scribase
```

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "scribase": {
      "url": "https://api.scribase.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SCRIBASE_ACCESS_TOKEN}" }
    }
  }
}
```

Add the project rule: copy `agents/templates/.cursor/rules/scribase.mdc` to
`.cursor/rules/`.

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.scribase]
url = "https://api.scribase.com/mcp"
bearer_token_env_var = "SCRIBASE_ACCESS_TOKEN"
```

Append `agents/templates/AGENTS.md` to your project's `AGENTS.md`.

### Windsurf

`~/.codeium/windsurf/mcp_config.json`, the same as Cursor with `serverUrl`
instead of `url`. Copy `agents/templates/.windsurf/rules/scribase.md` to
`.windsurf/rules/`.

## Local stdio server

Build it once from the repository (Rust 1.85+):

```sh
cargo install --locked --path crates/mcp
```

Your editor starts `scribase-mcp` itself. Schema tools (`schema.propose`,
`policy.simulate`, `policy.test`, `schema.apply`, `sql.explain`) run on a
scratch Postgres the server starts (it needs `initdb`, `pg_ctl` and `psql` on
`PATH`), or on the cluster in `PGHOST`. Control tools use `SCRIBASE_API_URL`
and `SCRIBASE_ACCESS_TOKEN`.

```json
{
  "mcpServers": {
    "scribase": {
      "command": "scribase-mcp",
      "env": {
        "SCRIBASE_API_URL": "https://api.scribase.com",
        "SCRIBASE_ACCESS_TOKEN": "${env:SCRIBASE_ACCESS_TOKEN}"
      }
    }
  }
}
```

## The CLI, for agents that prefer a shell

```sh
cargo install --locked --path crates/scribase-cli
scribase login --json   # device sign-in: prints a link + code, waits for your approval
scribase doctor         # checks the URL and the token
scribase help           # the exact command list
```

The CLI reads the same `SCRIBASE_API_URL` and `SCRIBASE_ACCESS_TOKEN`, so an
agent can mix MCP tools and CLI commands in one session.

---

Source: https://docs.scribase.com/docs/agents/no-secret-keys

# Why you never need to paste a secret key

Paste a `service_role` key or a database password into Claude Code, Codex or
Cursor and a good agent will stop: it will not echo it, may refuse to use it,
and asks you to rotate it. It is right. A pasted secret lives on in the chat
transcript, in the model provider's logs and in whatever the agent writes
next, it grants everything, and it never expires.

Scribase is built so you never have to. Every way an agent gets access is
either a browser approval (no secret leaves the console) or a token designed
to be shared with an agent.

## Three ways in, none of them a secret key

### 1. `scribase login`: approve the agent in your browser

The agent runs one command and shows you a link and a short code:

```sh
scribase login --json
```

```json
{"event":"device_authorization","verification_uri":"https://console.scribase.com/device","verification_uri_complete":"https://console.scribase.com/device?user_code=SCRB-7F3K-Q2MX","user_code":"SCRB-7F3K-Q2MX","expires_in":600}
```

You open the link (the console asks you to sign in if needed), check that the
code matches, and see who is asking and for what: the client name, the
requested scopes, the address the request came from. Pick the organization,
one project (or all), the access level, the capabilities to allow and how
long it lasts (8 hours by default), then **Approve** or **Deny**.

The command, which has been polling, receives its own agent token and stores
it in the operating system keychain (macOS Keychain, or the Secret Service on
Linux through `secret-tool`), falling back to
`~/.config/scribase/credentials` with mode `0600`. It never prints the token;
the last line is only the outcome:

```json
{"ok":true,"status":"approved","organization_id":"acme","project_id":"web","scopes":["project:web:write","sql:write","migrations:write"],"expires_at":1790028000,"stored_in":"keychain"}
```

`npx scribase login` does the same without installing the full CLI, and
`npx scribase init` runs this flow automatically when you are not signed in.
Agents whose shell only shows output after a command ends can use
`--no-wait`: it prints the link and exits, and running `scribase login` again
picks the same request back up. This is the OAuth 2.0 Device Authorization
Grant (RFC 8628); see [Device login API](https://docs.scribase.com/docs/api/device-login.md).

### 2. MCP with OAuth

Add the hosted MCP server without a header, and your editor opens the
Scribase consent screen the first time it connects; you choose the access
there. See [Connect your agent](https://docs.scribase.com/docs/agents/setup.md).

### 3. A temporary project

No account at all:

```sh
npx scribase init --temp --yes --json
```

The agent gets a 72-hour project and an agent token scoped to it; you keep the
project by opening the claim link. See
[Temporary databases](https://docs.scribase.com/docs/agents/temporary-databases.md).

## Paste-safe agent tokens (`scb_agt_`)

Sometimes pasting is simplest: you are in a hosted agent with no browser, or
you want to hand one project to one session. Agent tokens are made for that.
On **Account > Access tokens**, **Copy for your AI agent** creates one and
copies a message the agent understands:

```text
Scribase agent token (scoped to project web, read/write, expires in 8h,
revocable at https://console.scribase.com/account/tokens). Designed to be
shared with coding agents: scb_agt_1p-rw-sqlw-mig-fn-x2609260412_3f9a...
```

The token describes itself. After `scb_agt_` comes a short, readable summary,
then the secret:

| Part | Meaning |
|---|---|
| `1p` / `np` / `all` / `org` | One project, several named projects, every project, or organization read only |
| `ro` / `rw` / `admin` | Read, read/write, or admin on those projects |
| `sql` / `sqlw` | Read-only SQL, or read-write SQL |
| `mig`, `fn`, `br` | Apply migrations, deploy functions, write branches |
| `keys` | Can read secret keys (never set by *Copy for your AI agent*) |
| `x2609260412` | Expires 2026-09-26 04:12 UTC (`xnever` if it does not expire) |

The summary is for people and agents to read; the server ignores it and
trusts only the token's digest, so editing it just makes the token invalid.

Why it is safe to share:

- **Scoped.** One project by default, and only the capabilities you chose. It
  can never do more than you can, and can never mint tokens, manage members,
  billing or SSO.
- **Short-lived.** 8 hours by default for copy-paste tokens.
- **Revocable.** One click on the tokens page, effective on the next request.
- **Audited.** Every request it makes is recorded (method, path, status,
  address) under *Activity*.
- **No secret keys.** Without the `keys:secret` scope, the keys route returns
  only the public (anon) key, and SQL never runs as a superuser. Copy-paste
  tokens never carry `keys:secret`.

The worst a leaked copy-paste token can do is what you allowed on one project
for a few hours, and you can see and stop it.

## Never paste these

| Secret | Instead |
|---|---|
| `service_role` / `sb_secret_` keys | They bypass row level security. Keep them in server-side env only; an agent that needs admin work gets a scoped token |
| Database passwords and connection strings | Agents use SQL and migrations through the API with an agent token |
| Personal access tokens (`scb_pat_`) | They are you, in every organization. Use `scribase login` or an agent token |
| Organization API keys (`sbk_`) | Meant for CI secret stores, not chats |

If one of these ended up in a chat, revoke or rotate it now (tokens under
**Account > Access tokens**, keys in the project's settings), then sign the
agent in with `scribase login`.

## What our agent rules say

The rules and skills we ship for Claude Code, Codex, Cursor and Windsurf
(see [Build with AI agents](https://docs.scribase.com/docs/agents.md)) tell the agent: never ask for API
keys, service-role keys or passwords; authenticate with `scribase login`, or
`npx scribase init --temp` for a throwaway project; a pasted `scb_agt_` token
is designed for agents and fine to use (kept in `SCRIBASE_ACCESS_TOKEN` or the
gitignored env file, never committed); anything else that looks like a secret
is not repeated back, and the user is asked to revoke it and use login.

---

Source: https://docs.scribase.com/docs/agents/safety

# Tokens and safety

An agent acts with exactly the permissions of the token you give it. Give it
the smallest one that does the job, with an expiry, and revoke it when the
work is done.

## Choosing a token

| Token | Prefix | Permissions | Expiry | Best for |
|---|---|---|---|---|
| **Agent token** | `scb_agt_` | Only its scopes, never more than yours; optionally one organization | Default 8 hours (`30m` to `never`) | Any coding agent |
| Personal access token | `scb_pat_` | Yours, in every organization you belong to | Optional, 1 to 365 days | Your own CLI on your own machine |
| Organization API key, `read` | `sbk_` | Viewer: read everything, change nothing | None; revoke it | An agent that only inspects and explains |
| Organization API key, `deploy` | `sbk_` | Developer: environments, migrations, functions, secrets | None; revoke it | Agents that build features, CI |
| Organization API key, `admin` | `sbk_` | Admin: also members, keys, auth providers | None; revoke it | Rarely; setup work you watch |

The easiest way to give an agent one is not to create it yourself: the agent
runs `scribase login` and you approve it in the browser (see
[Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md)). To
hand one over directly, use **Copy for your AI agent** under **Account >
Access tokens**: an 8-hour token for one project, without secret keys, copied
together with a note that tells the agent it is meant to be shared. Or create
one from the CLI:

```sh
scribase token create my-agent \
  --scope project:web:write --scope sql:write --scope migrations:write \
  --ttl 8h --org acme
scribase token list
scribase token events <id>     # every request it made
scribase token revoke <id>
```

Agent tokens describe themselves: `scb_agt_1p-rw-sqlw-mig-fn-x2609260412_...`
reads as one project, read/write, read-write SQL, migrations, functions,
expiring 2026-09-26 04:12 UTC. The summary is display-only; the server
trusts only the token's digest. Tokens created before this format
(`scb_agt_` followed directly by the secret) keep working.

| Scope | Grants |
|---|---|
| `org:read` | Organizations, project lists, operations, usage (any project scope implies it) |
| `project:<id>:read` | Read one project (`project:*:read` for every project) |
| `project:<id>:write` | Change it: environments, auth, storage, functions invoke, secrets names |
| `project:<id>:admin` | Destructive changes on **production**, backups, restores, domains, key rotation |
| `sql:read` / `sql:write` | The SQL routes, read-only or read-write |
| `migrations:write` | Apply migrations |
| `functions:deploy` | Deploy or delete edge functions |
| `branches:write` | Create, merge and delete branches and previews |
| `keys:secret` | The `service_role` / secret key, connection strings, environment secrets; without it the keys route returns only the public keys |

How they are enforced, on every request, by the control API itself:

- **Least privilege.** A request outside the scopes gets
  `403 insufficient_scope` with the missing scope in `WWW-Authenticate`. The
  organization role the request runs with is capped by the scopes (admin,
  developer or viewer), so a token can never do more than its owner.
- **Protected production.** Drops, deletes, `confirm: true` SQL, restores and
  key rotations on a production environment need `project:<id>:admin`; with
  `write` they are refused there and allowed on branches and previews.
- **No escalation.** Agent tokens cannot mint tokens, manage members,
  organization keys, billing or SSO, or claim temporary projects.
- **SQL never runs as a superuser.** With an agent token, SQL on a connection
  that is a superuser drops to the project's `postgres` role for the
  transaction.
- **Expiry, revocation, rate limits.** Tokens expire (8 hours unless you
  choose), revocation is immediate, and each token is limited to 300
  requests a minute (`SCRIBASE_AGENT_TOKEN_REQUESTS_PER_MINUTE`).
- **Audit log.** Every request is recorded with method, path, status and
  client address (never bodies, headers or secrets):
  `GET /v1/account/tokens/{id}/events`, `scribase token events <id>`, or
  *Activity* on the tokens page. `last_used_at` is updated on each use.

Organization keys are created and revoked under **Organization > API tokens**
or with `POST /v1/organizations/{org}/api-keys` (see
[Access tokens & API keys](https://docs.scribase.com/docs/api/tokens.md)). Secrets are shown once;
Scribase stores only a digest. `apikey.list` shows names and scopes, never
values, and `apikey.revoke` revokes one.

## Guardrails on every call

- **Mutations need `confirm: true`.** Every MCP tool that changes something
  (`project.put`, `environment.create`, `environment.delete`, `migrate.run`
  with `apply`, `branch.merge`, `backup.restore`, `apikey.revoke`, ...)
  refuses without it and returns the exact request it would send, so you
  approve that specific change.
- **SQL is read-only.** `database.query` runs one `SELECT`, `WITH` or
  `EXPLAIN` inside a bounded read-only transaction; writes and DDL are
  rejected. Schema changes go through migrations, which are linted before
  they apply.
- **RLS is proven before it ships.** `schema.apply` only accepts a schema
  that `policy.test` has proved on a scratch branch, including deliberately
  broken variants of each policy that the tests must catch.
- **Isolated scratch databases.** The remote MCP server gives each session
  its own scratch branch and drops it at the end.
- **Idempotency keys.** Every create carries one, so a retried call never
  creates a second environment.
- **Secrets stay out of output.** Tokens are redacted from the MCP server's
  debug output; `apikey.list` and `secrets list` return names only; the
  skills and rules tell agents never to print keys and to write them to
  `.env` instead.
- **Audit log.** Every control-plane change is recorded with the credential
  that made it. Read it with `audit.list` or `scribase audit list <org>`.

## Rules we ship to agents

The `agents/` templates (see [Build with AI agents](https://docs.scribase.com/docs/agents.md)) add these
rules to the agent's context: never ask the user for keys or passwords (sign
in with `scribase login` or use a temporary project), treat a pasted
`scb_agt_` token as safe to use, never print or commit keys, only the anon key
in client code, schema changes only through migrations, RLS in the same
migration as the table, a preview branch per task, and explicit approval for
production merges, deletes, key rotations and restores.

---

Source: https://docs.scribase.com/docs/agents/branch-per-task

# Branch per task

A preview environment is a copy of production (sanitized by default) with its
own URL, keys and database, and a time to live. An agent can migrate, seed
and break it freely; production only changes when you approve a merge.

## The loop

```sh
TASK=add-invoices
scribase env create acme my-app "pr-$TASK" preview sanitized aws-eu-central-1 "create-pr-$TASK" 24
scribase operation get acme <operation-id>                 # until succeeded
scribase branch register acme my-app "pr-$TASK" --base production
scribase apps switch acme my-app --env "pr-$TASK" --format dotenv > .env.preview

scribase migrate acme my-app "pr-$TASK" --dir supabase/migrations --apply
scribase gen types acme my-app "pr-$TASK" --out src/database.types.ts

scribase branch diff  acme my-app production "pr-$TASK"
scribase branch merge acme my-app production "pr-$TASK" --dry-run
```

The agent shows you the diff and the dry run. After you approve:

```sh
scribase backup create acme my-app production "pre-$TASK"
scribase branch merge  acme my-app production "pr-$TASK"
scribase env delete    acme my-app "pr-$TASK" "delete-pr-$TASK"
```

Over MCP the same steps are `environment.create`, `operation.get`,
`branch.register`, `migrate.run`, `branch.diff`, `branch.merge`,
`backup.create` and `environment.delete`. The `scribase-safe-change` skill
walks an agent through this loop, including the RLS proof with
`policy.test`.

## Data modes

| Mode | What the preview gets |
|---|---|
| `sanitized` | A copy of the parent's data, then anonymized. The default for previews. |
| `snapshot` | An exact copy. Only when you ask for real data. |
| `schema_only` | Schema, no rows. |

## Pull requests

Link the preview to its pull request so each shows the other:

```sh
scribase branch pr acme my-app "pr-$TASK" github acme/app 42
```

A preview is removed automatically when its TTL expires. Extend it with
`scribase env renew acme my-app "pr-$TASK" 24 "renew-pr-$TASK"`.

See [Branching](https://docs.scribase.com/docs/concepts/branching.md) for how branches work underneath.

---

Source: https://docs.scribase.com/docs/agents/temporary-databases

# Temporary databases

## Claimable temporary projects

An agent can get a real backend (Postgres, auth, storage, realtime,
functions) without an account:

```sh
npx scribase init --temp --yes --json
```

It detects the framework (Next.js, Expo, Vite, plain Node), creates a
temporary project, writes the env file with the framework's variable names
(`NEXT_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_URL`, `VITE_SUPABASE_URL`,
or `SUPABASE_URL`, plus the anon key), installs `@supabase/supabase-js`,
writes a small client module and prints one JSON object with the project URL,
the variables it wrote and a **claim URL**.

- The project lives **72 hours**. To keep it, open the claim URL, sign up (or
  sign in) and add a card (the one-time card check). The project moves to your
  account unchanged: same URL, same keys, nothing to reconfigure.
- Unclaimed projects are deleted, with their database, when they expire.
- The agent gets a token scoped to that one project (`SCRIBASE_ACCESS_TOKEN` in
  the env file), so it can keep running SQL and migrations. It expires with
  the project.
- Limits while unclaimed: small database, storage and egress caps, and the
  project's auth never sends email (sign-ups are confirmed automatically).
  Creating one may ask for a few seconds of proof of work, which
  `npx scribase init` does for you; each address can create a handful a day.

The same flow over HTTP:

| Call | What it does |
|---|---|
| `POST /v1/temporary-projects/challenge` | `{challenge, bits}` for the proof of work |
| `POST /v1/temporary-projects` | `{name, challenge, nonce}` → `201` with `agent_token`, `claim_url`, `expires_at` |
| `GET /v1/temporary-projects/{id}` | with the agent token: `status` (`provisioning`, `ready`) and, when ready, `keys` |
| `POST /v1/temporary-projects/{id}/claim` | a signed-in person with `{claim_token}`: `claimed`, or `402 card_required` until the card is added |

The deployment operator turns this on with `SCRIBASE_TEMPORARY_PROJECTS=1`
(and sets `SCRIBASE_TEMPORARY_PROJECTS_SECRET`); a deployment without it
answers `503 temporary_projects_disabled`.

## With your account

With a token (`scribase login`, or `SCRIBASE_ACCESS_TOKEN`),
`npx scribase init --yes --json` creates (or, run again, reuses) a project in
your organization and writes the same files. Give an agent a scoped token for
this: see [Tokens and safety](https://docs.scribase.com/docs/agents/safety.md).

If the folder is linked to Vercel (`vercel link`), `init` also sets the URL and
keys on the Vercel project for development, preview and production, using
`VERCEL_TOKEN` or the signed-in `vercel` CLI. See
[vercel env push](https://docs.scribase.com/docs/cli/vercel.md).

## Other short-lived databases

- **MCP scratch branch.** Every remote MCP session gets its own scratch
  database for `schema.propose`, `policy.simulate`, `policy.test` and
  `sql.explain`. It is dropped when the session ends.
- **Previews with a TTL.** `scribase env create <org> <project> <env> preview
  schema_only <region> <key> <ttl-hours>` (MCP `environment.create` with
  `kind: "preview"` and `ttl_hours`) gives the agent a real environment, with
  URL, keys, auth and storage, that deletes itself when the TTL runs out.
  `schema_only` starts empty; `sanitized` copies production's data, then
  anonymizes it.
- **Local databases.** `scribase dev` runs Postgres, auth and storage on your
  machine with no account at all.

---

Source: https://docs.scribase.com/docs/cli

# CLI Reference

The `scribase` CLI is the primary interface for both local development and the
production control-plane management API. It has no library dependencies beyond
the binary itself and `curl` for API calls.

## Configuration

```sh
export SCRIBASE_API_URL=https://api.scribase.com   # or your self-hosted gateway
export SCRIBASE_ACCESS_TOKEN=<token>               # see /docs/api/tokens
# Optional: override the curl binary
export SCRIBASE_CURL_BINARY=/usr/local/bin/curl
```

Or run [`scribase login`](https://docs.scribase.com/docs/cli/login.md) once, which stores the URL and a
token; the environment variables always win over the stored values.

Plain HTTP is only accepted for `localhost`, `127.0.0.1`, and `[::1]`. The
access token and request bodies are piped to `curl` through stdin configuration
and never appear in process arguments or debug output.

## Command groups

| Command | Description |
|---|---|
| [`doctor`](https://docs.scribase.com/docs/cli/doctor.md) | Check API connectivity and token configuration |
| [`login`, `logout`, `whoami`, `token`](https://docs.scribase.com/docs/cli/login.md) | Sign in with a token or the built-in password login; manage personal access tokens |
| [`admin`](https://docs.scribase.com/docs/admin-login.md) | Create the first built-in administrator, hash an admin password |
| [`org`, `project`, `env`, `member`](https://docs.scribase.com/docs/cli/resources.md) | Create and read organizations, projects and environments |
| [`backup`, `restore`](https://docs.scribase.com/docs/cli/backup.md) | Take, verify and restore backups |
| [`apps switch`](https://docs.scribase.com/docs/cli/apps.md) | Print the URL and public key an app needs |
| [`gen types`](https://docs.scribase.com/docs/cli/gen-types.md) | TypeScript `Database` types for supabase-js |
| [`vercel env push`](https://docs.scribase.com/docs/cli/vercel.md) | Set the URL and keys on the linked Vercel project |
| [`dev`](https://docs.scribase.com/docs/cli/dev.md) | Local database and service stack |
| [`migrate`](https://docs.scribase.com/docs/cli/migrate.md) | Run migrations against a remote environment |
| [`db pull`](https://docs.scribase.com/docs/cli/db-pull.md) | Capture a remote schema as a local migration file |
| [`branch`](https://docs.scribase.com/docs/cli/branch.md) | Manage branches (local and remote) |
| [`queue`](https://docs.scribase.com/docs/cli/queue.md) | Interact with environment queues |
| [`import`](https://docs.scribase.com/docs/cli/import.md) | Import a schema or migrate a Supabase project |
| [`export`](https://docs.scribase.com/docs/cli/export.md) | Export a runnable bundle for an environment, then list and download it |
| [`functions`](https://docs.scribase.com/docs/cli/functions.md) | Deploy, inspect, invoke and roll back edge functions |
| [`secrets`](https://docs.scribase.com/docs/cli/secrets.md) | Manage the secrets bound into an environment's functions |
| [`schema`](https://docs.scribase.com/docs/cli/schema.md) | Compile and test schema files |
| [`insights`](https://docs.scribase.com/docs/cli/insights.md) | Analyze a live environment for improvements |
| `operation` | Poll a running operation |
| `audit` | List audit events |
| `version` | Print CLI version |

## Resource commands

These follow the pattern `scribase <resource> <action> [args...]`.

### org

```sh
scribase org put <org-id> <display-name>
scribase org get <org-id>
```

### member

```sh
scribase member put <org-id> <subject> <owner|admin|developer|viewer>
```

### project

```sh
scribase project put <org-id> <project-id> <region>
scribase project get <org-id> <project-id>
```

### env

```sh
scribase env create <org> <project> <env> <kind> <data-mode> <region> <idempotency-key> [ttl-hours]
scribase env get <org> <project> <env>
scribase env suspend <org> <project> <env> <idempotency-key>
scribase env resume  <org> <project> <env> <idempotency-key>
scribase env delete  <org> <project> <env> <idempotency-key>
```

**Environment kinds:** `production`, `preview`, `development`

**Data modes:** `snapshot`, `schema-only`, `empty`

### operation

```sh
scribase operation get <org-id> <operation-id>
```

Operations are asynchronous. Poll until `state` is `succeeded` or `failed`.

### audit

```sh
scribase audit list <org-id>
scribase audit list <org-id> <after-cursor> <limit>
```

Limit must be between 1 and 200.

---

Source: https://docs.scribase.com/docs/cli/doctor

# scribase doctor

Verifies that the management API is reachable and that your access token is
configured correctly.

## Usage

```sh
scribase doctor
```

## What it checks

1. **Endpoint configured** — `SCRIBASE_API_URL` is set and is a valid URL.
2. **Management API ready** — `GET /health/ready` returns `204`.
3. **Access token present** — `SCRIBASE_ACCESS_TOKEN` is set (it is not
   validated against the API in this check, only for presence).

## Output

```
management API: ready
endpoint: configured
access token: configured
```

If the API is unreachable:

```
management API readiness returned HTTP 503
```

## Configuration

| Variable | Required | Description |
|---|---|---|
| `SCRIBASE_API_URL` | Yes | Base URL of the management API |
| `SCRIBASE_ACCESS_TOKEN` | No | Token presence is reported but not required for doctor |

## Notes

`doctor` does not authenticate. It calls `/health/ready` without a bearer token
so it can distinguish a reachable-but-unauthenticated failure from a
network-level failure. Use it as a first step when debugging connectivity
problems.

---

Source: https://docs.scribase.com/docs/cli/login

# login, whoami and token

```sh
scribase login [--json] [--no-wait] [--scope <s>]... [--name <client>] [--no-browser] [--api-url <url>]
                                                     # device login: approve in the browser
scribase login --token <pat> [--api-url <url>]      # verify and store a personal access token
scribase login --with-token [--api-url <url>]       # the same, reading the token from stdin
scribase login --email <email> [--api-url <url>]    # built-in password (+ TOTP) sign-in
scribase logout                                      # delete the stored credentials
scribase whoami                                      # GET /v1/account
scribase token list                                  # GET /v1/account/tokens
scribase token create <name> [--expires-in-days N]   # POST /v1/account/tokens
scribase token revoke <token-id>                     # DELETE /v1/account/tokens/{id}
```

## login in the browser (device login)

```sh
scribase login
```

The CLI prints a link and a code such as `SCRB-7F3K-Q2MX`, opens your browser
when it runs in a terminal, and waits. In the console you check the code,
choose the organization, project, access level, capabilities and lifetime (8
hours by default), and approve. The CLI then receives its own agent token
(`scb_agt_…`) with exactly what you approved, and stores it; it never prints
it. This is the flow coding agents use, so nobody pastes a secret into a chat
(see [Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md)
and the [Device login API](https://docs.scribase.com/docs/api/device-login.md)).

| Flag | Effect |
|---|---|
| `--json` | One JSON line with `verification_uri_complete` and `user_code` right away, then one line with the outcome (`{"ok":true,"status":"approved",...}` or `{"ok":false,"error":{"code":"access_denied"}}`) |
| `--no-wait` | Print the link and code and exit; run `scribase login` again to pick the same request back up |
| `--scope <s>` | Request specific scopes (repeatable). Default `project:write sql:write migrations:write functions:deploy branches:write` |
| `--name <client>` | The name shown on the approval page |
| `--no-browser` | Do not open a browser |

`npx scribase login` does the same from the npm package, and
`npx scribase init` starts it automatically when you are not signed in.

## login with a personal access token

Create a token in the console under **Account > Access tokens**, then:

```sh
scribase login --with-token --api-url https://api.example.com < token.txt
```

`--with-token` reads the token from standard input so it stays out of your
shell history; `--token <pat>` takes it as an argument. The CLI checks it against `GET /v1/account` first and only
stores it if the API accepts it. A rejected token stores nothing.

## login with the built-in password

On a control plane running `SCRIBASE_AUTH_MODE=builtin` (see
[Built-in admin login](https://docs.scribase.com/docs/admin-login.md)):

```sh
scribase login --email you@example.com --api-url https://api.example.com
```

The password is read from the terminal with echo off, never from arguments. If
the account has an authenticator app, the CLI then asks for a code. The session
this stores ends after the control plane's idle and absolute timeouts (2 and 12
hours by default), so use a token for automation.

## Where credentials live

`login` keeps the token in the operating system keychain when there is one
(macOS Keychain through `security`, the Secret Service on Linux through
`secret-tool`) and writes only `api_url` to
`$XDG_CONFIG_HOME/scribase/credentials` (default
`~/.config/scribase/credentials`, mode `0600`). Without a keychain, or with
`SCRIBASE_NO_KEYCHAIN=1`, the token goes into that file too. `SCRIBASE_ACCESS_TOKEN` and
`SCRIBASE_API_URL` in the environment always take precedence over the stored
values, which is what CI should use. `logout` deletes the file and the keychain entry.

## Tokens

```sh
scribase whoami
scribase token create ci-deploy --expires-in-days 90
scribase token list
scribase token revoke <token-id>
```

`token create` prints the secret once. Scribase stores only a SHA-256 digest
and a short display prefix. `token list` shows metadata (name, prefix, created,
last used, expiry), never the secret. Revoke a token as soon as it may have
leaked.

Organization API keys for CI and bots are created in the console under
**Organization > API tokens** or over the API. See
[Access tokens & API keys](https://docs.scribase.com/docs/api/tokens.md).

---

Source: https://docs.scribase.com/docs/cli/resources

# org, project and env

These commands are thin wrappers over the `/v1` control API. They need a
signed-in CLI (see [login](https://docs.scribase.com/docs/cli/login.md)) or `SCRIBASE_API_URL` and
`SCRIBASE_ACCESS_TOKEN` in the environment. Every response is printed as JSON.

## Organizations and members

```sh
scribase org put <org> <display-name>        # create or rename
scribase org get <org>
scribase member put <org> <subject> <owner|admin|developer|viewer>
```

Ids (organization, project, environment) are 1 to 63 characters of letters,
digits, `-` and `_`, starting and ending with a letter or digit. On the single-box
layout, the first organization's id is `SCRIBASE_ORGANIZATION_ID`.

## Projects

```sh
scribase project put <org> <project> <region>
scribase project get <org> <project>
scribase project engine <org> <project>
scribase project move <org> <project> --engine neon-local|neon-cloud [--delete-source]
```

- `project put` creates the project on Postgres 17. Use a region id the
  provider honours, for example `aws-eu-central-1`, `aws-us-east-1` or
  `aws-ap-southeast-1` (the console lists them). Any other id is placed in the
  platform's default region.
- `project engine` shows the database engine the project runs on (managed Neon,
  self-hosted Neon, or the box's Postgres), any engine move in progress, and
  what the engine has provisioned for each environment.
- `project move` queues a move to another engine. The data is copied and the
  connection switched. The project's URL and API keys stay the same. Writes
  pause while the data is copied, and the source database is kept unless you
  pass `--delete-source`.

## Environments

```sh
scribase env create <org> <project> <env> <kind> <data-mode> <region> <idempotency-key> [ttl-hours]
scribase env get <org> <project> <env>
scribase env suspend <org> <project> <env> <idempotency-key>
scribase env resume  <org> <project> <env> <idempotency-key>
scribase env delete  <org> <project> <env> <idempotency-key>
scribase env renew   <org> <project> <env> <ttl-hours> <idempotency-key>
```

| Argument | Values |
|---|---|
| `kind` | `production`, `staging`, `preview` |
| `data-mode` | `snapshot` (copy of the parent's data), `sanitized` (copy, then anonymized), `schema_only` |
| `ttl-hours` | Optional. A preview is swept when it expires; `env renew` extends it from now |
| `idempotency-key` | Any unique string. Re-running a command with the same key returns the original result instead of repeating the change |

Example:

```sh
scribase env create acme my-app production production snapshot aws-eu-central-1 prod-create-1
scribase env create acme my-app pr-42 preview sanitized aws-eu-central-1 pr-42-create 72
```

## Operations and audit

Mutations return an operation id. Poll it until it finishes:

```sh
scribase operation get <org> <operation-id>
scribase audit list <org> [after limit]
```

## Not yet in the CLI

The CLI cannot list organizations, projects or environments yet, and cannot
delete a project. Use the console or the API
([Organizations](https://docs.scribase.com/docs/api/organizations.md), [Projects](https://docs.scribase.com/docs/api/projects.md),
[Environments](https://docs.scribase.com/docs/api/environments.md)) for those.

---

Source: https://docs.scribase.com/docs/cli/backup

# backup and restore

```sh
scribase backup list    <org> <project> <env> [--limit N]
scribase backup create  <org> <project> <env> <idempotency-key>
scribase backup get     <org> <project> <env> <backup>
scribase backup verify  <org> <project> <env> <backup> <idempotency-key>
scribase restore start  <org> <project> <backup> <target-env> <idempotency-key> [--source <env>]
scribase restore list   <org> <project> <env>
scribase restore get    <org> <project> <env> <restore>
```

Each command is one authenticated request to the `/v1` API. Backups and
restores are long-running jobs: `create`, `verify` and `restore start` return
the record at once, and `backup get` / `restore get` poll it until it finishes.
Scheduled backups and retention also run on their own inside the control API.

## Take a backup

```sh
scribase backup create acme my-app production nightly-2026-09-25
scribase backup list acme my-app production --limit 20
scribase backup get acme my-app production <backup-id>
```

`--limit` takes 1 to 200.

## Verify a backup

```sh
scribase backup verify acme my-app production <backup-id> verify-2026-09-25
```

Verify restores the backup into a throwaway database, counts its relations and
the tables protected by row-level security, then drops it. It never touches the
environment's own database. The control plane needs a scratch Postgres for this
(`SCRIBASE_RESTORE_VERIFY_DATABASE_URL`; the single-box layout bundles one).
Without it, verify answers `503 verification_not_configured`.

## Restore

```sh
# Restore a production backup into production.
scribase restore start acme my-app <backup-id> production restore-1

# Restore a production backup into a staging environment.
scribase restore start acme my-app <backup-id> staging restore-2 --source production

scribase restore list acme my-app production
scribase restore get acme my-app production <restore-id>
```

`--source` names the environment the backup was taken from. It defaults to the
target environment.

On the [single-box layout](https://docs.scribase.com/docs/single-box.md), a restore into an environment
that already has data lands in a new `restore_<id>` database next to the
current one. The environment keeps serving its current database until you
switch it to the restored one in the console (restore history, **Switch**).
Switching back works the same way.

## Extend a preview

```sh
scribase env renew <org> <project> <env> <ttl-hours> <idempotency-key>
```

Sets a preview environment's expiry to `ttl-hours` from now, so it is not swept.

See also the API reference: [Backups & restore](https://docs.scribase.com/docs/api/backups.md).

---

Source: https://docs.scribase.com/docs/cli/apps

# apps switch

```sh
scribase apps switch <org> <project> [--env production] [--format expo|dotenv|json] [--key anon|publishable]
```

`apps switch` reads the environment's client keys
(`GET .../environments/{env}/api-keys`) and prints the two values an app built
on `supabase-js` needs. Nothing else in the app has to change:
`createClient(url, key)` keeps working.

| Flag | Default | Meaning |
|---|---|---|
| `--env` | `production` | The environment to point at |
| `--format` | `expo` | `expo`: `EXPO_PUBLIC_SUPABASE_URL` / `EXPO_PUBLIC_SUPABASE_ANON_KEY` lines. `dotenv`: `SUPABASE_URL` / `SUPABASE_ANON_KEY`. `json`: one object for scripts |
| `--key` | `anon` | `anon` prints the legacy anon JWT, which every `supabase-js` version accepts. `publishable` prints the `sb_publishable_...` key |

## Example

```sh
scribase apps switch acme my-app > .env.production
```

```sh
# Scribase environment acme/my-app/production
# createClient(process.env.EXPO_PUBLIC_SUPABASE_URL, process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY) needs no other change.
EXPO_PUBLIC_SUPABASE_URL=https://<label>.<domain>
EXPO_PUBLIC_SUPABASE_ANON_KEY=eyJ...
#
# NEVER put the service_role or sb_secret_ key in an app: ...
#
# Native sign-in reads these environment auth settings ...
#   site_url (GOTRUE_SITE_URL): your app's scheme, e.g. myapp://
#   ...
```

Only the two assignments are real values. Everything else is comments.

## What it never prints

The `service_role` and `sb_secret_...` keys bypass row-level security, and
everything in an app bundle is public. `apps switch` never prints them. Server
code that needs them reads them from the console's API keys page or the API
(see [Environment API keys](https://docs.scribase.com/docs/api/environment-keys.md)).

## Auth settings for native sign-in

The output also names the environment auth settings that native Apple and
Google sign-in (`signInWithIdToken`) depend on. Set them on the environment's
**Auth** page in the console. They are environment settings, not app config:

| Setting | Variable | Value |
|---|---|---|
| `site_url` | `GOTRUE_SITE_URL` | The app's scheme, for example `myapp://` |
| `uri_allow_list` | `GOTRUE_URI_ALLOW_LIST` | Every `redirectTo` the app passes, for example `myapp://**`, plus `exp://**` for Expo Go |
| `external.apple.enabled` | `GOTRUE_EXTERNAL_APPLE_ENABLED` | `true` |
| `external.apple.client_id` | `GOTRUE_EXTERNAL_APPLE_CLIENT_ID` | The iOS bundle id, plus the Services ID if the web flow is used, comma-separated |
| `external.google.enabled` | `GOTRUE_EXTERNAL_GOOGLE_ENABLED` | `true` |
| `external.google.client_id` | `GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID` | The web, iOS and Android OAuth client ids, comma-separated |
| `external.google.skip_nonce_check` | `GOTRUE_EXTERNAL_GOOGLE_SKIP_NONCE_CHECK` | `true` only if the iOS Google SDK flow cannot pass a nonce |

## Errors

- **No public URL**: the control plane has no gateway base URL configured
  (`SCRIBASE_GATEWAY_BASE_URL` or `SCRIBASE_GATEWAY_BASE_URL_TEMPLATE`), so
  there is nothing an app could reach.
- **URL is not https**: only `https://` URLs, or `http://localhost` /
  `http://127.0.0.1` for local development, are accepted.
- **No publishable key**: use `--key anon`.

Moving an existing Supabase project first? See [import](https://docs.scribase.com/docs/cli/import.md),
which ends with the same switch.

---

Source: https://docs.scribase.com/docs/cli/gen-types

# gen types

```sh
scribase gen types --db-url <postgres-url> [--schema public,app] [--out FILE]
scribase gen types <org> <project> <env>   [--schema public,app] [--out FILE]
scribase gen types --env <org>/<project>/<env> [--schema public,app] [--out FILE]
```

Writes a TypeScript `Database` type in the shape `supabase-js` expects, so
`createClient<Database>(url, key)` gives typed tables, views, functions and
enums. `gen typescript` is an alias.

| Flag | Default | Meaning |
|---|---|---|
| `--schema` | `public` | Comma-separated schemas to include |
| `--out` | standard output | Write the file here instead |

## From an environment

```sh
scribase gen types acme my-app production --out src/database.types.ts
```

The control plane introspects the environment's database and returns the file.
A CI job needs only an access token, not database credentials.

## From a database URL

```sh
scribase gen types --db-url "$(scribase dev url)" --out src/database.types.ts
```

With `--db-url` the CLI reads the schema directly through `psql` (so `psql`
must be on the `PATH`). This works against a local `scribase dev` database, a
branch, or any Postgres.

Both paths run the same query and renderer, so they produce the same file for
the same schema.

## In CI

```sh
export SCRIBASE_API_URL=https://api.example.com
export SCRIBASE_ACCESS_TOKEN=${{ secrets.SCRIBASE_TOKEN }}
scribase gen types acme my-app production --out src/database.types.ts
git diff --exit-code src/database.types.ts   # fail if the committed types are stale
```

---

Source: https://docs.scribase.com/docs/cli/vercel

# vercel env push

```sh
scribase vercel env push <org> <project> <env> [--dir <path>] [--dry-run] [--json]
scribase vercel status [--dir <path>]
```

Writes the environment's project URL and keys into the Vercel project this
folder deploys to, for **development, preview and production**, in one
request. The next deploy uses them. Run it again after a key rotation: it
updates the values in place.

```sh
vercel link                                   # once, if the folder is not linked yet
scribase vercel env push acme shop production
# Vercel: 9 environment variables set on prj_… for development, preview and production (via VERCEL_TOKEN); the next deploy uses them
```

## Automatic in `npx scribase init`

You usually do not need this command. `npx scribase init` pushes the same
variables right after it provisions the backend and writes your `.env` file,
whenever the folder is linked to Vercel. It prints one line:

| Line | Meaning |
|---|---|
| `Vercel env updated for development, preview, production` | Done; redeploy to pick them up |
| `Not linked to Vercel — skipped` | No `.vercel/project.json` and no `VERCEL_PROJECT_ID` |
| `No Vercel credentials — skipped` | Linked, but no `VERCEL_TOKEN` and no signed-in `vercel` CLI |
| `Vercel env not updated: …` | Vercel refused; the reason follows. Retry with `scribase vercel env push` |

With `--json`, the result includes the outcome:

```json
{ "ok": true, "...": "...", "vercel": { "status": "updated", "targets": ["development", "preview", "production"], "project_id": "prj_…" } }
```

`status` is `updated`, `not_linked`, `no_credentials`, `failed` (with an
`error` string) or `disabled` (`--no-vercel`). Vercel never fails `init`: the
backend and your `.env` are ready either way.

Pass `--no-vercel` to leave the Vercel project alone.

## How the project is found

In order:

1. `VERCEL_PROJECT_ID` (and `VERCEL_ORG_ID`), the variables Vercel's own CLI
   reads in CI.
2. `.vercel/project.json` in the folder (`--dir`, default the current one),
   written by `vercel link` or `vercel deploy`.

No link means nothing to do. `scribase vercel status` shows what was found and
which credentials would be used.

## How it authenticates

- **`VERCEL_TOKEN`** set: Scribase calls the Vercel REST API directly. The
  token is only sent in the `Authorization` header (the Rust CLI streams it to
  curl on stdin); it is never put on a command line or printed.
- **Otherwise, a signed-in `vercel` CLI** (`npx vercel login` once): Scribase
  runs `vercel api` without a shell and passes the request body on stdin, so
  the CLI's own session is used and Scribase never reads a Vercel token.

Neither available: nothing is pushed, and the message says how to fix it.

## What gets set

The same names as the console's Vercel integration, so either path gives the
same result:

| Variable | Type | Targets |
|---|---|---|
| `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SCRIBASE_URL` | plain | development, preview, production |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `NEXT_PUBLIC_SCRIBASE_ANON_KEY` | plain | development, preview, production |
| `SCRIBASE_ORG`, `SCRIBASE_PROJECT`, `SCRIBASE_ENV` | plain | development, preview, production |
| `SUPABASE_SERVICE_ROLE_KEY`, `SCRIBASE_SERVICE_ROLE_KEY` | sensitive | preview, production |

The anon key is public by design (row level security applies). The
service-role key bypasses row level security, so it is **server-only**: it never
gets a `NEXT_PUBLIC_` prefix, and it is stored as a sensitive variable that
cannot be read back from the Vercel dashboard. Vercel does not allow sensitive
variables on the development target; for local development it lives in your
`.env` file, which `init` writes.

The request is `POST /v10/projects/{id}/env?upsert=true` (plus `teamId` for a
team project) with every variable in one JSON array.

## Flags

| Flag | Meaning |
|---|---|
| `--dir <path>` | Folder to read `.vercel/project.json` from (default: current) |
| `--dry-run` | Print the variable names, types and targets that would be set; send nothing |
| `--json` | Print the outcome as JSON: `{"vercel":"pushed", "project_id", "count", "via", "keys"}`, or `not_linked`, `no_credentials`, `failed` |

`vercel env push` exits non-zero when nothing was pushed (unlike `init`,
where it is only a report).

## Environment

| Variable | Meaning |
|---|---|
| `VERCEL_TOKEN` | Vercel access token; optional when the `vercel` CLI is signed in |
| `VERCEL_PROJECT_ID`, `VERCEL_ORG_ID` | Use this project instead of `.vercel/project.json` |
| `SCRIBASE_VERCEL_BINARY` | Path to the `vercel` CLI (default: `vercel` on `PATH`) |
| `SCRIBASE_VERCEL_API_URL` | Vercel API origin (default: `https://api.vercel.com`) |

---

Source: https://docs.scribase.com/docs/cli/dev

# scribase dev

Boots the full local Scribase stack — Postgres plus optional application
services — with no Docker and no configuration file required. All state is
kept in `.scribase/` beside your project (or in `SCRIBASE_HOME`).

## Subcommands

### `scribase dev` (bare)

Starts the full local stack: Postgres, auth, storage, realtime, and edge
functions. Blocks until interrupted (Ctrl-C). Equivalent to `scribase dev serve`.

```sh
scribase dev
```

### `scribase dev --services <list>`

Boot only a subset of services. Comma-separated list.

```sh
scribase dev --services auth,storage
scribase dev --services realtime
```

Valid service names: `auth`, `storage`, `realtime`, `functions` (alias: `edge`). Use `all` to enable every service.

Before starting, a **preflight** lists which service binaries were found next to the `scribase` executable or on `PATH`:

```
preflight: service binaries
  auth       found    /usr/local/bin/gotrue
  storage    MISSING  `storage-api`
```

A missing binary is dropped from the boot set with a message; the remaining services still come up.

### `scribase dev up [--schema FILE]`

Starts the local Postgres cluster only (no application services). Prints the connection string and returns.

```sh
scribase dev up
scribase dev up --schema ./schema.scribase
```

With `--schema`, the schema file is compiled and applied immediately after the database is ready.

### `scribase dev status`

Shows every local database cluster and branch.

```sh
scribase dev status
```

Output:

```
primary                  running  primary
my-feature               stopped  branch
```

### `scribase dev url`

Prints the primary database connection string.

```sh
scribase dev url
# postgresql://postgres:postgres@127.0.0.1:54322/postgres
```

### `scribase dev down`

Stops the local database, keeping data intact. `scribase dev up` brings it back.

```sh
scribase dev down
```

### `scribase dev destroy`

Stops and deletes all local databases and branch clusters. Irreversible.

```sh
scribase dev destroy
```

## Configuration

| Variable | Description |
|---|---|
| `SCRIBASE_HOME` | Override the `.scribase` workspace directory |

Service binary overrides:

| Variable | Default binary |
|---|---|
| `ORION_AUTH_BIN` | `gotrue` |
| `ORION_STORAGE_BIN` | `storage-api` |
| `ORION_REALTIME_BIN` | `realtime` |
| `ORION_FUNCTIONS_BIN` | `edge-runtime` |

## Notes

- The local Postgres cluster binds to a random available port. `scribase dev url` always shows the current address.
- Two checkouts of the same project do not share a database; deleting the checkout removes its databases.
- The local stack does not use Docker. The `scribase` binary manages Postgres process lifecycle directly.

---

Source: https://docs.scribase.com/docs/cli/migrate

# scribase migrate

Sends a set of migrations to the control-plane API for a specific environment.
Without `--apply` the server lints and plans only — run it that way first to
catch issues before they touch data. With `--apply` the lint must pass before
the migrations execute.

## Usage

```sh
# From a migrations directory (recommended)
scribase migrate <org> <project> <env> --dir ./migrations [--apply]

# From a pre-built migrations JSON file
scribase migrate <org> <project> <env> <migrations.json> [--apply]
```

## Migrations directory format

Scribase discovers `.sql` files in the directory. Two naming shapes are supported:

```
migrations/
├── 001_init.sql            # up-only migration
├── 002_add_users.up.sql    # up migration
├── 002_add_users.down.sql  # paired down migration (optional)
├── 003_indexes.sql
```

Files are ordered by their numeric prefix. The version is the digits before the
first `_`; the name is everything after. Requirements:

- The version prefix must be positive digits.
- The name must not be empty.
- No two files may share the same version.
- A `.down.sql` file must have a matching `.up.sql`.
- Files must not be empty.

## Migrations JSON format

The JSON file must contain an array. Each element:

```json
{
  "version": "1",
  "name": "init",
  "up": "CREATE TABLE ...",
  "down": "DROP TABLE ..."
}
```

`"down"` is optional.

## Options

| Flag | Description |
|---|---|
| `--dir <path>` | Load migrations from a directory of `.sql` files |
| `--apply` | Execute after lint passes (default: lint only) |

## Example

```sh
# Lint first — review the plan before applying
scribase migrate acme store production --dir ./migrations

# Apply after review
scribase migrate acme store production --dir ./migrations --apply
```

## Notes

- Migrations are sent to `POST /v1/organizations/{org}/projects/{project}/environments/{env}/migrations`.
- The server returns a lint report. Review findings before running with `--apply`.
- The migration runner is idempotent by version. Re-sending an already-applied version is a no-op.
- `--apply` is `false` by default — this is intentional. Always review the plan on the first run.
- To capture changes made directly on a database back into this directory, use [`scribase db pull`](https://docs.scribase.com/docs/cli/db-pull.md).

---

Source: https://docs.scribase.com/docs/cli/db-pull

# scribase db pull

Reads the schema of a live database and writes the difference from your local
migrations as a new migration file. Use it to adopt a database that was changed
by hand (or in the Studio) back into version control.

## Usage

```sh
# Pull from a Scribase environment (needs a writer role on the organization)
scribase db pull <org> <project> <env> [--dir ./migrations]

# Pull from any Postgres URL
scribase db pull --db-url postgresql://user:pass@host:5432/app [--dir ./migrations]
```

`SCRIBASE_DB_URL` is used when neither an environment nor `--db-url` is given.
For an environment, the CLI asks the control API for the environment's
connection string (`GET .../environments/{env}/connection`) and connects to it
directly, so the database must be reachable from your machine.

## How it works

1. The remote schema is dumped with `pg_dump --schema-only --no-owner --no-privileges`.
2. If the migrations directory is empty or missing, the cleaned dump becomes the
   first migration.
3. Otherwise a temporary shadow database is created with `initdb`, every local
   migration is applied to it in version order, and it is dumped the same way.
4. The two dumps are compared object by object (tables column by column,
   indexes, constraints, defaults, policies, functions, views, triggers,
   sequences, enum labels, comments). Only the difference is written.
5. The remote ledger (`orion.schema_migrations`) is compared with the local
   files, and versions that exist on only one side are reported.

If nothing differs, no file is written.

## Options

| Flag | Description |
|---|---|
| `--db-url <url>` | Pull from this Postgres URL instead of an environment |
| `--dir <path>` | Migrations directory (default `migrations`) |
| `--schema <a,b>` | Schemas to pull, comma-separated (default `public`) |
| `--name <name>` | File name suffix (default `remote_schema`) |
| `--shadow-db-url <url>` | Use this empty database as the shadow instead of a temporary cluster |
| `--dry-run` | Print the migration instead of writing it |
| `--mark-applied` | Record the new file as applied in the remote `orion.schema_migrations` |

## File naming

The new file continues the directory's numbering: `003_remote_schema.sql` after
`002_...`, keeping the existing zero padding. A directory that uses timestamp
versions, or an empty one, gets a UTC timestamp such as
`20260924120000_remote_schema.sql`. Either shape is accepted by
[`scribase migrate`](https://docs.scribase.com/docs/cli/migrate.md).

## Destructive changes

Anything that would delete data (a dropped table, column, schema, extension, or
type) is written commented out with a `-- REVIEW` marker, and the command
prints how many there are. Uncomment only the ones you intend to apply. Other
removals (indexes, policies, constraints, functions, views, triggers) are
written as `DROP ... IF EXISTS`.

## Marking the pull as applied

The remote already has the schema you just pulled. Without `--mark-applied`,
a later `scribase migrate --apply` would try to run the new file there and fail
on objects that already exist. `--mark-applied` inserts the file's version,
name, and SHA-256 into the remote ledger, which is exactly what the migration
runner writes after applying a file itself.

## Requirements and limits

- `pg_dump`, `psql`, `initdb`, and `pg_ctl` on `PATH`, or in the directory set by
  `SCRIBASE_PG_BIN_DIR`. `pg_dump` must be at least the remote server's major
  version.
- The temporary shadow gets the Supabase roles (`anon`, `authenticated`,
  `service_role`) and `auth.uid()`, `auth.role()`, `auth.jwt()` and
  `auth.users` stubs, so typical app migrations apply. If your migrations need
  extensions that are not installed locally, pass `--shadow-db-url` pointing at
  an empty database that has them.
- Grants and ownership are not pulled.
- A changed composite type or table storage options are flagged with
  `-- REVIEW` rather than rewritten.

## Example

```sh
scribase db pull acme store production --dir ./migrations
# Wrote migrations/004_remote_schema.sql (6 statement(s)).

# Review the file, then record it as applied on the remote:
scribase db pull acme store production --dir ./migrations --mark-applied
```

---

Source: https://docs.scribase.com/docs/cli/branch

# scribase branch

Creates and manages database branches. Local branches use copy-on-write
snapshots of the local Postgres cluster; remote branches are registered with
the control-plane API and tied to pull requests or preview environments.

## Local branch commands

These operate on the local `.scribase/` workspace.

### `branch new <name> [--schema FILE]`

Creates a new branch from the current primary database. Prints the branch
connection string and returns immediately.

```sh
scribase branch new my-feature
# postgresql://postgres:postgres@127.0.0.1:54399/postgres
```

With `--schema`, the schema is compiled and applied to the new branch:

```sh
scribase branch new my-feature --schema ./schema.scribase
```

Copy-on-write branching is fast — typically under one second.

### `branch list` (local)

Lists all local branches and their status.

```sh
scribase branch list
```

Output:

```
my-feature               running   postgresql://...
old-experiment           stopped   postgresql://...
```

### `branch url <name>`

Prints the connection string for a named branch.

```sh
scribase branch url my-feature
```

### `branch delete <name>`

Stops and removes a local branch cluster.

```sh
scribase branch delete my-feature
```

---

## Remote branch commands

These call the control-plane API and require `SCRIBASE_API_URL` and
`SCRIBASE_ACCESS_TOKEN`.

### `branch register <org> <project> <env> [--base <parent-env>]`

Registers an environment as a branch of another, capturing the parent's schema
as the merge base. This is the first step before a `branch merge` or `branch diff`.

```sh
scribase branch register acme store pr-42 --base production
```

### `branch list <org> <project>`

Lists all remote branches registered for a project.

```sh
scribase branch list acme store
```

### `branch diff <org> <project> <base-env> <head-env>`

Shows the schema diff between two environments.

```sh
scribase branch diff acme store production pr-42
```

Returns a list of changed objects: added, modified, and removed tables, columns,
functions, and policies.

### `branch merge <org> <project> <base-env> <head-env> [--force]`

Merges the schema from `head-env` into `base-env`.

```sh
scribase branch merge acme store production pr-42
```

Without `--force`, the merge fails if there are conflicts. With `--force`, the
head schema wins on any conflict.

### `branch pr <org> <project> <env> <provider> <repo> <number> [--url-template <t>]`

Links a branch to a pull request. Supported providers: `github`, `gitlab`,
`bitbucket`, `generic`.

```sh
scribase branch pr acme store pr-42 github acme/store 42
scribase branch pr acme store pr-42 generic my-repo 42 --url-template "https://git.example.com/{repo}/pr/{number}"
```

---

## Workflow example

```sh
# 1. Create a branch for a feature
scribase branch new feat-payments

# 2. Develop against the branch
psql "$(scribase branch url feat-payments)"

# 3. Register the remote environment as a branch
scribase branch register acme store feat-payments --base production

# 4. Open a PR and link it
scribase branch pr acme store feat-payments github acme/store 12

# 5. Review the diff
scribase branch diff acme store production feat-payments

# 6. Merge when approved
scribase branch merge acme store production feat-payments
```

---

Source: https://docs.scribase.com/docs/cli/queue

# scribase queue

Manages durable message queues inside a Scribase environment. All queue
operations call `POST /v1/organizations/{org}/projects/{project}/environments/{env}/queues/{queue}` — the action verb travels in the request body.

## Usage

```sh
scribase queue <action> <org> <project> <env> <queue> [args]
```

## Actions

### `create`

Creates a new queue.

```sh
scribase queue create acme store production events
```

### `send`

Sends a JSON message to a queue. The message must be valid JSON.

```sh
scribase queue send acme store production events '{"type":"order","id":42}'
```

With a delivery delay (in seconds):

```sh
scribase queue send acme store production events '{"type":"order"}' --delay 30
```

### `read`

Reads one or more messages. Messages become invisible to other readers during the visibility timeout.

```sh
scribase queue read acme store production events
scribase queue read acme store production events --quantity 10 --visibility 60
```

| Flag | Description |
|---|---|
| `--quantity N` | Number of messages to read (default 1) |
| `--visibility N` | Visibility timeout in seconds (default: queue default) |

### `archive`

Archives a message by ID after processing. Archived messages are retained for inspection.

```sh
scribase queue archive acme store production events 12345
```

### `delete`

Permanently deletes a message by ID.

```sh
scribase queue delete acme store production events 12345
```

### `purge`

Deletes all messages in a queue.

```sh
scribase queue purge acme store production events
```

## Notes

- Queue names follow the same identifier rules as environment IDs.
- Message IDs are returned in the `msg_id` field of send and read responses.
- Use `archive` after successful processing to keep a record. Use `delete` to remove without archiving.

---

Source: https://docs.scribase.com/docs/cli/import

# scribase import

Two shapes share one verb:

- `scribase import <url>` — reads an existing Postgres database and produces a Scribase schema file.
- `scribase import supabase ...` — migrates a live Supabase project into a Scribase environment via the management API.

---

## Import a schema from a URL

Connects to an existing Postgres database, introspects its columns, constraints,
and RLS policies, and emits a `.scribase` schema file.

```sh
scribase import <connection-url> [--out FILE] [--partial]
```

### Options

| Flag | Description |
|---|---|
| `--out <file>` | Write output to file instead of stdout |
| `--partial` | Allow incomplete import (some columns may not be expressible) |

### Example

```sh
scribase import "postgresql://user:pass@host/db" --out schema.scribase
```

### Notes

- Any column type, constraint, or default that cannot be expressed in the Scribase schema language is printed as a **fidelity note**. Without `--partial`, the command fails if there are any such notes.
- Tables without row-level security are printed as **security notes** — they are imported but the output warns you.
- Use `--partial` when working with complex legacy schemas and iterating toward full coverage.

---

## Migrate from Supabase

Migrates a live Supabase project into a Scribase environment. The source project's schema and data are read and applied to the destination environment.

```sh
scribase import supabase \
  --project-ref <supabase-project-ref> \
  --org <scribase-org-id> \
  --project <scribase-project-id> \
  --env <scribase-env-id> \
  [--connection-string <url>] \
  [--service-key <key>] \
  [--dry-run]
```

### Options

| Flag | Env override | Description |
|---|---|---|
| `--project-ref` | — | Supabase project reference ID |
| `--org` | — | Destination Scribase organization ID |
| `--project` | — | Destination Scribase project ID |
| `--env` | — | Destination Scribase environment ID |
| `--connection-string` | `SCRIBASE_SOURCE_CONNECTION_STRING` | Supabase database URL |
| `--service-key` | `SCRIBASE_SOURCE_SERVICE_KEY` | Supabase service role key |
| `--schemas a,b` | — | Copy only these schemas (default: every application schema) |
| `--no-storage` | — | Skip buckets and objects |
| `--dry-run` | — | Plan what would move without touching anything |
| `--no-wait` | — | Start the import and print its `import_id` without following progress |
| `--functions-dir DIR` | — | After the data import succeeds, deploy every edge function in this local `supabase/functions` directory (ignored with `--dry-run`) |
| `--functions-only` | — | Skip the data import and only deploy the functions (`--functions-dir` defaults to `supabase/functions`) |

The connection string and service key are secrets. Pass them via environment variables rather than on the command line in production contexts.

### Example

```sh
export SCRIBASE_SOURCE_CONNECTION_STRING="postgresql://..."
export SCRIBASE_SOURCE_SERVICE_KEY="eyJhbGci..."

scribase import supabase \
  --project-ref abcdefghijkl \
  --org acme \
  --project store \
  --env production \
  --dry-run
```

The server returns a report describing what would be imported. Remove `--dry-run` to execute: the server starts the import in the background, and the command follows `GET /v1/imports/{import_id}`, printing each phase as it starts, then prints the verified report. Pressing Ctrl-C stops watching, not the import.

### Edge functions

```sh
# Data first, then every function in the local checkout:
scribase import supabase --project-ref <ref> --org acme --project store --env production \
  --functions-dir supabase/functions

# Or only the functions, for example after a data import that already finished:
scribase import supabase --functions-only --org acme --project store --env production \
  --functions-dir supabase/functions
```

Function secrets are never read from the source. Re-enter them with
[`scribase secrets set`](https://docs.scribase.com/docs/cli/secrets.md).

### What is migrated

In order, each step replay-safe (`--resume <import_id>` continues from the last committed step):

1. **Extensions** the app schemas use (best effort; any the target cannot install is listed as an action item).
2. **Schema** of every application schema (`public` plus any schema that Supabase or an extension does not own): tables, types, functions and RPCs, views, indexes, `ENABLE ROW LEVEL SECURITY`. Foreign keys and triggers are held back until after the data, as `pg_restore` does.
3. **Grants**: the exact privileges `anon`, `authenticated` and `service_role` hold on every schema, table, sequence and function (revokes included, so an RPC hidden from `anon` stays hidden).
4. **Auth**: `auth.users` with ids and bcrypt `encrypted_password` hashes byte for byte, plus `instance_id`, `aud` and `role` (the lookup columns GoTrue uses on sign-in); `auth.identities` (`provider`, `provider_id`, `identity_data`), so Apple and Google `signInWithIdToken` users resolve to the same user id; `auth.mfa_factors` (TOTP secrets verbatim).
5. **Data**, page by page, keyset-paged and idempotent.
6. **Post-data**: foreign keys, table triggers, sequence positions (`setval`), and triggers on `auth.users` / `storage.objects` that call app functions (for example `on_auth_user_created`).
7. **RLS policies** on the app schemas and on `storage.objects` / `storage.buckets`, with their `auth.uid()` / `auth.jwt()` expressions unchanged.
8. **Storage**: buckets, then each object's bytes through the destination environment's storage API (`x-upsert`, so a resume overwrites), then the object's original `owner_id`, so owner-based storage policies keep matching.
9. **Verification**: per-table row counts and checksums, policy parity, auth user and identity counts, object counts, and an optional login proof.

### What is not migrated

- **Sessions and refresh tokens.** Scribase signs with its own JWT secret, so every existing session ends. Users sign in once more after the switch, with the same password or the same Apple/Google account, and keep their user id and data.
- **API keys and the JWT secret.** They are never copied. The app gets the environment's own keys (see below).
- **Edge function source from the hosted project.** The Supabase API cannot reliably hand back function source, so functions move from your local checkout instead: pass `--functions-dir supabase/functions` (or run `--functions-only` later) and the CLI deploys each function, honouring `_shared`, `deno.json` / import maps and `verify_jwt` in `config.toml`. The console import wizard does not move functions yet.
- **Vault secrets and function env vars** (listed by name; re-enter with `scribase secrets set`), **custom auth hooks, SMTP, and auth provider settings** (set them on the environment's Auth page), **`realtime` publications**, **`pg_cron` jobs**, and **column-level grants**.
- Keyless tables (no single-column primary key) are protected against duplicates on a resume, not on a second fresh run. Import into an empty environment.

## Switch an Expo app to Scribase

The end-to-end procedure for a mobile app (Expo + `supabase-js`, email/password plus native Apple/Google sign-in):

1. **Create the environment** (console, or `scribase env create ...`). Open its Storage page once so the storage service creates its schema.
2. **Dry run**, then **import**:

   ```sh
   export SCRIBASE_SOURCE_CONNECTION_STRING="postgresql://postgres:...@db.<ref>.supabase.co:5432/postgres"
   export SCRIBASE_SOURCE_SERVICE_KEY="<source service_role key>"
   scribase import supabase --project-ref <ref> --org <org> --project <app> --env production --dry-run
   scribase import supabase --project-ref <ref> --org <org> --project <app> --env production
   ```

   Proceed only when the verdict is `VERIFIED`.
3. **Configure auth on the environment** (Auth page), mirroring the Supabase project's Auth settings: `site_url`, the redirect allow list (`myapp://**`, plus `exp://**` for Expo Go), and for native sign-in the Apple provider (client id = the iOS bundle id, plus the Services ID if you also use the web flow) and the Google provider (client ids = the web, iOS and Android OAuth client ids, comma-separated). The console also asks for each provider's client secret.
4. **Print the app config**:

   ```sh
   scribase apps switch <org> <app> --env production            # .env lines for Expo
   scribase apps switch <org> <app> --format json               # for scripts
   scribase apps switch <org> <app> --key publishable           # sb_publishable_ key instead of the anon JWT
   ```

   It prints exactly `EXPO_PUBLIC_SUPABASE_URL=https://<label>.<domain>` and `EXPO_PUBLIC_SUPABASE_ANON_KEY=<key>`, plus the auth setting names above. It never prints the `service_role` / `sb_secret_` key. That key must never ship in an app, because it bypasses row-level security.
5. **Update the app**: put the two values in `.env` (or the EAS environment), rebuild, and ship. `createClient(url, key)` needs no code change.
6. **Cut over**: rehearse steps 2 to 5 against a `staging` environment first. At cutover, stop writes on the Supabase project (or force-update the old app version), import into the still-empty `production` environment, and release the build that points at it. The URL and key printed in step 4 are fixed once the environment exists, so the build can be prepared before the final import. Existing users see the sign-in screen once.

---

Source: https://docs.scribase.com/docs/cli/export

# scribase export

Assembles a signed, runnable bundle for a Scribase environment: the database
archive, storage objects, auth users and policies, rendered as a Docker Compose
project or Kustomize manifests, with a manifest of SHA-256 digests over every
artifact and an HMAC-SHA256 signature.

An export is a background job. `export create` queues it; the control plane's
export worker dumps, packs and boot-checks the bundle, then marks it
`available`. `export download --wait` follows it to completion and saves the
bundle.

## Usage

```sh
scribase export [create] <org> <project> <env> [--format compose|kustomize] [--schema-only] [--no-storage] [--wait] [--out FILE]
scribase export list <org> [<project>]
scribase export get <org> <export>
scribase export download <org> <export> [--out FILE] [--wait] [--timeout SECONDS] [--force]
```

## Options

| Flag | Applies to | Description |
|---|---|---|
| `--format` | `create` | Output format: `compose` (default) or `kustomize` |
| `--schema-only` | `create` | Leave table data out of the database archive |
| `--no-storage` | `create` | Leave storage objects out of the bundle |
| `--wait` | `create`, `download` | Wait for the export to become available, then download it |
| `--out` | `create --wait`, `download` | Where to save the bundle (default `<export>.tar.gz`) |
| `--timeout` | `create --wait`, `download --wait` | Longest time to wait, in seconds (default 1800) |
| `--force` | `download` | Overwrite an existing output file |

## Examples

```sh
# Queue a Docker Compose export and print its record (state "requested")
scribase export acme store production

# Queue a Kustomize export, wait for it, and save the bundle
scribase export create acme store production --format kustomize --wait --out store.tar.gz

# Every export in the organization, or in one project
scribase export list acme
scribase export list acme store

# One export's manifest, including a short-lived signed download link once available
scribase export get acme ex-3f9a1c2b7d4e5f60

# Download an existing export
scribase export download acme ex-3f9a1c2b7d4e5f60 --out store.tar.gz
```

## States

| State | Meaning |
|---|---|
| `requested` | Queued for the export worker |
| `packing`, `verifying` | Being dumped and bundled, then boot-checked |
| `available` | Ready; `export get` returns a signed `download_url` |
| `failed` | The worker stopped; `error` says why |
| `expired` | Past its retention; the bundle file was removed |

`export download` refuses to overwrite an existing file unless you pass
`--force`. It writes to `<out>.part` and renames the file only after a complete
download, so an interrupted download never leaves a truncated bundle behind.

## Notes

- The API routes are `POST /v1/organizations/{org}/projects/{project}/environments/{env}/exports`,
  `GET /v1/organizations/{org}/exports`, `GET /v1/organizations/{org}/projects/{project}/exports`
  and `GET /v1/organizations/{org}/exports/{export}`. See [Exports](https://docs.scribase.com/docs/api/exports.md).
- The signed download link carries its own authorization and expires after a
  short time; run `export get` again for a fresh one.
- Exports need `SCRIBASE_EXPORT_SIGNING_KEY_ID` and `SCRIBASE_EXPORT_SIGNING_KEY`
  set on the control plane. Without them the create route answers `503`.
- Verify the manifest signature before you deploy an exported bundle to production.

---

Source: https://docs.scribase.com/docs/cli/functions

# scribase functions

Manages the edge functions of a hosted environment through the management API.
Every deploy is a new immutable version; the runtime boots it once and makes it
active only if the boot succeeds, so a broken deploy never replaces a working
one.

## Usage

```sh
scribase functions list     <org> <project> <env>
scribase functions deploy   <org> <project> <env> <name> <dir|file> [--import-map FILE]
scribase functions get      <org> <project> <env> <name> [--version N]
scribase functions logs     <org> <project> <env> <name> [--limit N]
scribase functions invoke   <org> <project> <env> <name> [--data JSON | --data-file FILE]
scribase functions rollback <org> <project> <env> <name> <version>
scribase functions delete   <org> <project> <env> <name>
```

## Deploying

Point `deploy` at a function directory or a single entrypoint file:

- **Directory** — `index.ts` is the entrypoint. Every module beside it and in
  its subdirectories (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.mts`, `.json`) is
  sent with it. Hidden entries, `node_modules`, `tests` and `__tests__` are
  skipped. An `import_map.json` in the directory is used as the import map.
- **File** — the file becomes the function's `index.ts`.

`--import-map FILE` uses an import map from anywhere on disk. A deploy may
contain at most 64 modules and 2 MiB of source.

```sh
scribase functions deploy acme store production hello ./functions/hello
```

The environment's secrets are bound into the function at deploy time and kept
current afterwards. See [`scribase secrets`](https://docs.scribase.com/docs/cli/secrets.md).

## Options

| Flag | Applies to | Description |
|---|---|---|
| `--import-map` | `deploy` | Path to an import map JSON file |
| `--version` | `get` | Show the source of a retained earlier version |
| `--limit` | `logs` | Number of lines, 1-200 (default 100) |
| `--data` | `invoke` | JSON payload sent to the function |
| `--data-file` | `invoke` | Read the JSON payload from a file (up to 1 MiB) |

## Logs

`logs` returns the newest lines first. They include one line per invocation
(method, path, status and duration), deploy and rollback markers, and the
function's own `console.*` output, uncaught exceptions and limit terminations.

```sh
scribase functions logs acme store production hello --limit 50
```

## Rolling back

The runtime keeps the 20 most recent versions. `get` lists them; `rollback`
makes an earlier one active again without redeploying:

```sh
scribase functions get acme store production hello
scribase functions rollback acme store production hello 4
```

---

Source: https://docs.scribase.com/docs/cli/secrets

# scribase secrets

Environment secrets are encrypted at rest and bound into every edge function in
the environment, where a function reads them with `Deno.env.get('NAME')`.
Changing a secret reaches deployed functions without a redeploy: the next
request after the change runs with the new value.

## Usage

```sh
scribase secrets list  <org> <project> <env>
scribase secrets set   <org> <project> <env> <NAME> [<value> | --from-env VAR | --stdin]
scribase secrets unset <org> <project> <env> <NAME>
```

`set` needs exactly one value source:

| Source | Example |
|---|---|
| `--from-env VAR` | `scribase secrets set acme store production STRIPE_KEY --from-env STRIPE_KEY` |
| `--stdin` | `printf %s "$KEY" \| scribase secrets set acme store production STRIPE_KEY --stdin` |
| A literal value | `scribase secrets set acme store production FEATURE_FLAG on` |

Prefer `--from-env` or `--stdin`: a literal value lands in your shell history
and the process list. A trailing newline on standard input is not part of the
secret.

## Rules

- Names are letters, digits and underscores, starting with a letter or
  underscore. Names beginning with `SCRIBASE_` are reserved for the platform.
- Values are 1 byte to 64 KiB.
- `list` shows names and versions, never values.
- `set` on an existing name rotates it and bumps its version.

The response's `functions_refreshed` field is `true` once the running functions
have the change. If the functions runtime could not be reached, the change is
still saved, a warning is written to the environment's logs, and functions pick
it up on their next deploy.

---

Source: https://docs.scribase.com/docs/cli/schema

# scribase schema

Works with Scribase schema files — the typed model-definition language that
compiles to Postgres DDL with RLS policies baked in.

## Subcommands

### `schema compile <file> [--out FILE]`

Compiles a schema file to Postgres SQL. Validates the schema and reports any
errors or warnings.

```sh
scribase schema compile schema.scribase
scribase schema compile schema.scribase --out schema.sql
```

Without `--out`, the SQL is printed to stdout. With `--out`, it is written to
the given file.

### `schema test <file>`

Runs the Aegis policy tests embedded in the schema file. Tests are declared
inline with the schema and verify RLS policy behavior against synthetic
authenticated contexts.

```sh
scribase schema test schema.scribase
```

Output shows each test, its expected outcome, and pass/fail status. A non-zero
exit code means at least one test failed.

## Schema file format

A `.scribase` file defines models (tables) with typed columns, constraints, and
RLS policies in a concise declarative syntax. Example:

```scribase
model orders {
  id         uuid primary key default gen_random_uuid()
  user_id    uuid not null references auth.users
  total      numeric(12,2) not null check (total > 0)
  created_at timestamptz not null default now()

  policy "owner can read" on select
    using (auth.uid() = user_id)

  policy "owner can insert" on insert
    with check (auth.uid() = user_id)
}
```

The compiler generates:
- `CREATE TABLE` with columns and constraints
- `ALTER TABLE ENABLE ROW LEVEL SECURITY`
- `CREATE POLICY` for each declared policy
- `GRANT` statements for application roles

## Notes

- Run `schema test` in CI to catch policy regressions before deployment.
- `schema compile` can be used to preview the SQL before sending it to the server.
- The Scribase schema language is a superset of what `scribase import` can read back from an existing database.

See [Aegis Policy Compiler](https://docs.scribase.com/docs/aegis.md) for the full policy testing reference.

---

Source: https://docs.scribase.com/docs/cli/insights

# scribase insights

Analyzes a live environment or an offline schema snapshot for improvements. It
reports findings across three dimensions: missing RLS policies, suboptimal
indexes, and slow query patterns.

## Usage

### Analyze a live environment

```sh
scribase insights <org> <project> <env>
```

Connects to the live environment via the management API and analyzes its current
state. Requires `SCRIBASE_API_URL` and `SCRIBASE_ACCESS_TOKEN`.

### Analyze offline (no server)

```sh
scribase insights \
  --policies schema.scribase \
  --tables schema.scribase \
  [--statements queries.sql] \
  [--foreign-keys schema.scribase] \
  [--json]
```

All inputs are read locally — no API call is made. Useful for CI policy audits.

## Options (offline mode)

| Flag | Description |
|---|---|
| `--policies <file>` | Schema file to analyze for policy coverage (`F` = skip) |
| `--tables <file>` | Schema file to analyze for missing indexes |
| `--statements <file>` | SQL file of representative queries for index advice |
| `--foreign-keys <file>` | Schema file to check for unindexed foreign keys |
| `--json` | Output findings as JSON |

## Output

Each finding has:

- **severity** — `critical`, `high`, `medium`, `info`
- **confidence** — `certain`, `likely`, `possible`
- **message** — description of the finding
- **remediation** — suggested fix (SQL or policy syntax)

Example:

```json
{
  "findings": [
    {
      "severity": "critical",
      "confidence": "certain",
      "message": "Table 'orders' has no RLS policies and RLS is not enabled.",
      "remediation": "ALTER TABLE orders ENABLE ROW LEVEL SECURITY;"
    },
    {
      "severity": "high",
      "confidence": "likely",
      "message": "Foreign key orders.user_id is not indexed.",
      "remediation": "CREATE INDEX ON orders (user_id);"
    }
  ]
}
```

## Notes

- `scribase insights` is read-only. It does not modify the database.
- In live mode the API fetches real query statistics from `pg_stat_statements`.
- In offline mode only structural analysis is possible (no query statistics).
- Run in CI with `--json` to fail the build on critical findings.

---

Source: https://docs.scribase.com/docs/api

# Control API /v1

The Scribase management API is an authenticated HTTP/1.1 REST API that manages
organizations, projects, environments, migrations, branches, queues, and more.

## Base URL

| Deployment | Base URL |
|---|---|
| Hosted Scribase | `https://api.scribase.com` |
| Self-hosted / BYOC | Your own gateway, e.g. `https://api.<your-domain>` |

Self-hosted, the server listens on `127.0.0.1:8080` by default and requires a
TLS-terminating proxy or Ingress in front of it for production use. The CLI
reads the base URL from `SCRIBASE_API_URL`; the SDK takes it as `baseUrl`.

## Authentication

All endpoints except `/health/live` and `/health/ready` require a Bearer token:

```http
Authorization: Bearer <token>
```

On hosted Scribase, create a personal access token in the console under
**Account → Access tokens**, or via
[`POST /v1/account/tokens`](https://docs.scribase.com/docs/api/tokens.md). Organization API keys for CI and
services are created under **Organization → API tokens** or via
[`POST /v1/organizations/{org}/api-keys`](https://docs.scribase.com/docs/api/tokens.md). See the
[hosted quickstart](https://docs.scribase.com/docs/hosted.md) for the full sign-up-to-first-call path.

The token is verified via OIDC token introspection. Organization-level
authorization is then enforced by RLS membership state — the token's claims are
not used for authorization.

## Common request requirements

- `Content-Type: application/json` on all requests with a body.
- `Idempotency-Key: <key>` on all mutating endpoints (PUT, POST, DELETE). Keys must be 8–128 printable ASCII characters.
- `X-Scribase-Organization-ID: <org>` on the `operations` endpoint.

## Error format

Errors follow [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457)
with `Content-Type: application/problem+json`. The `type` is a URN, not a web
page, and the machine-readable `code` is repeated as its own field so clients
can branch on it directly:

```json
{
  "type": "urn:scribase:error:route_not_found",
  "title": "Not found",
  "status": 404,
  "code": "route_not_found",
  "detail": "the requested management API route does not exist"
}
```

Common codes include `invalid_json` (400), `missing_idempotency_key` (400),
`unsupported_media_type` (415), `unauthorized` (401), `forbidden` (403),
`route_not_found` (404), `conflict` (409), and `server_busy` (503). The SDK maps each
status to a typed error class (`NotFoundError`, `ConflictError`,
`QuotaExceededError`, ...).

## Asynchronous operations

Endpoints that change environment state return `202 Accepted` with an
`Operation` document:

```json
{
  "id": "op_01J...",
  "kind": "create_environment",
  "environment": {
    "organization_id": "acme",
    "project_id": "store",
    "environment_id": "production"
  },
  "state": "pending",
  "attempt_count": 0
}
```

`state` moves through `pending`, `running`, and `waiting_retry` to one of the
terminal states `succeeded`, `failed`, or `cancelled`.

Poll `GET /v1/operations/{id}` (with `X-Scribase-Organization-ID`) until
`state` is terminal. The SDK's `operations.wait()` does this
automatically.

## Resources

| Resource | Endpoint prefix | Description |
|---|---|---|
| [Access tokens & API keys](https://docs.scribase.com/docs/api/tokens.md) | `/v1/account/tokens`, `.../api-keys` | Credentials for the CLI, SDK, and CI |
| [Organizations](https://docs.scribase.com/docs/api/organizations.md) | `/v1/organizations` | Tenant-level containers |
| [Projects](https://docs.scribase.com/docs/api/projects.md) | `/v1/organizations/{org}/projects` | Logical groupings within an org |
| [Environments](https://docs.scribase.com/docs/api/environments.md) | `/v1/environments` | Postgres environments, previews, TTL renewal, usage |
| [Backups & restore](https://docs.scribase.com/docs/api/backups.md) | `.../environments/{env}/backups`, `.../backups/{id}/restore` | Verified backups and restore |
| [Exports](https://docs.scribase.com/docs/api/exports.md) | `.../environments/{env}/exports`, `.../projects/{project}/export` | Runnable, signed export bundles |
| [Migrations](https://docs.scribase.com/docs/api/migrations.md) | `.../environments/{env}/migrations` | Schema migrations |
| [Branches](https://docs.scribase.com/docs/api/branches.md) | `.../projects/{project}/branches` | Schema-level branches |
| [Queues](https://docs.scribase.com/docs/api/queues.md) | `.../environments/{env}/queues` | Durable message queues |
| [Imports](https://docs.scribase.com/docs/api/imports.md) | `/v1/imports` | Supabase project migration |
| [Operations](https://docs.scribase.com/docs/api/operations.md) | `/v1/operations` | Async operation polling |
| [Audit Events](https://docs.scribase.com/docs/api/audit.md) | `.../audit-events` | Organization audit log |
| [Data-plane views](https://docs.scribase.com/docs/api/data-plane.md) | `.../environments/{env}/{auth,database,storage,functions,realtime,metrics,insights,logs}` | Read-only views into a live environment |

## OpenAPI spec

The server embeds its OpenAPI contract. Print it with:

```sh
scribase-control-api openapi
# or via HTTP:
curl http://localhost:8081/openapi.yaml
```

---

Source: https://docs.scribase.com/docs/api/tokens

# Access tokens & API keys

Every `/v1` call carries `Authorization: Bearer <credential>`. There are two
kinds of credential:

| Credential | Belongs to | Use it for | Create it in the console |
|---|---|---|---|
| Personal access token | You | Your own CLI and scripts | **Account → Access tokens** |
| Organization API key | An organization | CI, deploy bots, agents | **Organization → API tokens** |

Both secrets are shown exactly once at creation; Scribase stores only a SHA-256
digest and a short display prefix. Revoke a credential the moment it may have
leaked.

---

## Personal access tokens

Personal access token routes are authenticated by your own session or an
existing token.

### GET /v1/account/tokens

Lists your tokens (metadata only, never the secret).

```json
{
  "tokens": [
    {
      "id": "3f2c...",
      "name": "laptop",
      "token_prefix": "scb_pat_1a2b3c4d",
      "created_at": 1790000000,
      "last_used_at": 1790050000,
      "expires_at": 1797776000,
      "revoked_at": null
    }
  ]
}
```

### POST /v1/account/tokens

Creates a token. **Headers required:** `Content-Type: application/json`,
`Idempotency-Key`.

| Field | Type | Notes |
|---|---|---|
| `name` | string | 1–200 characters |
| `expires_in_days` | integer, optional | Omit for a non-expiring token |
| `ttl` | string, optional | Instead of `expires_in_days`: `30m`, `1h`, `24h`, `7d`, `30d`, `never` |
| `scopes` | string array, optional | Makes it an **agent token** (`scb_agt_…`) limited to these scopes; see [Tokens and safety](https://docs.scribase.com/docs/agents/safety.md). Without `ttl` it expires after 8 hours. Its `token` starts with a readable scope and expiry summary (`scb_agt_1p-rw-sqlw-x2609260412_…`) |
| `organization_id` | string, optional | Binds an agent token to one organization; required when a scope names a specific project |

The response and the list include `kind` (`personal` or `agent`), `scopes`
and `organization_id`. `GET /v1/account/tokens/{id}/events` returns the last
200 requests an agent token made (`method`, `path`, `status`, `client_ip`,
`at`).

```sh
curl -X POST "$SCRIBASE_API_URL/v1/account/tokens" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-ci-token-001' \
  -d '{"name": "ci", "expires_in_days": 90}'
```

**Response `201 Created`** — the only time `token` is returned:

```json
{
  "id": "7d1e...",
  "name": "ci",
  "token": "scb_pat_...",
  "token_prefix": "scb_pat_9f8e7d6c",
  "created_at": 1790000000,
  "expires_at": 1797776000
}
```

An agent token's response also carries `agent_message` and `revoke_url`.
`agent_message` is the text the console's "Copy for your AI agent" button
copies. It tells the agent what the string is, so the agent uses it instead of
refusing it:

```text
Scribase agent token (scoped to project web, read/write, SQL read/write,
migrations, no secret keys, expires in 8h, revocable at
https://console.scribase.com/account/tokens). Designed to be shared with coding
agents: scb_agt_1p-rw-sqlw-mig-x2609260412_...
```

Coding agents should not need a token created here at all: they sign in with
the [device flow](https://docs.scribase.com/docs/api/device-login.md) (`scribase login`), which a person
approves in the browser.

### DELETE /v1/account/tokens/{token_id}

Revokes a token immediately. **Headers required:** `Idempotency-Key`.

---

## Organization API keys

Creating and revoking keys requires the `owner` or `admin` role in the
organization.

### GET /v1/organizations/{org}/api-keys

```json
{
  "items": [
    {
      "api_key_id": "key_4c1d...",
      "organization_id": "acme",
      "name": "deploy-bot",
      "scopes": ["deploy"],
      "created_at_epoch_seconds": 1790000000,
      "last_used_epoch_seconds": 1790050000
    }
  ]
}
```

### POST /v1/organizations/{org}/api-keys

| Field | Type | Notes |
|---|---|---|
| `name` | string | 1–120 characters |
| `scopes` | string[] | Non-empty subset of `read`, `deploy`, `admin` |

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/api-keys" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "deploy-bot", "scopes": ["deploy"]}'
```

**Response `201 Created`** includes the `secret` (prefixed `sbk_`) once.

### DELETE /v1/organizations/{org}/api-keys/{api_key_id}

Revokes a key. **Headers required:** `Idempotency-Key`.

---

## SDK

```ts
const created = await scribase.account.createToken({ name: 'ci', expires_in_days: 90 });
await scribase.account.revokeToken(created.id);

const key = await scribase.organizations.createApiKey('acme', { name: 'deploy-bot', scopes: ['deploy'] });
await scribase.organizations.revokeApiKey('acme', key.api_key_id);
```

## Using a credential

```sh
export SCRIBASE_API_URL=https://api.scribase.com
export SCRIBASE_ACCESS_TOKEN=scb_pat_...
scribase doctor
```

---

Source: https://docs.scribase.com/docs/api/device-login

# Device login (OAuth device flow)

A CLI or coding agent that has no browser of its own gets a token without
anyone pasting a secret: it asks for a code, a person approves it in the
console, and the agent's next poll receives a scoped, expiring agent token
(`scb_agt_…`). This is the OAuth 2.0 Device Authorization Grant
([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)). `scribase login`,
`npx scribase login` and `npx scribase init` implement the client side; see
[Why you never need to paste a secret key](https://docs.scribase.com/docs/agents/no-secret-keys.md).

```text
agent                          control API                     person (console)
  | POST /v1/oauth/device/code  |                                     |
  |---------------------------->| device_code, user_code, URL         |
  |<----------------------------|                                     |
  | shows URL + SCRB-7F3K-Q2MX  |                                     |
  |                             |  /device?user_code=... (signed in)  |
  | POST /v1/oauth/token (poll) |<------------------------------------|
  | authorization_pending       |  lookup, then approve or deny       |
  | ...                         |                                     |
  | POST /v1/oauth/token        |                                     |
  | 200 access_token=scb_agt_…  |                                     |
```

## POST /v1/oauth/device/code

Anonymous. The body is `application/x-www-form-urlencoded` (as RFC 8628
specifies) or JSON.

| Field | Notes |
|---|---|
| `client_id` | Optional. Identifies the client, e.g. `scribase-cli` |
| `client_name` | Optional. Shown to the person approving, e.g. `Claude Code on laptop` (1 to 80 printable characters) |
| `scope` | Optional, space-separated. See below. Default `project:write sql:write migrations:write functions:deploy branches:write` |

Requested scopes: `org:read`, `project:read`, `project:write`,
`project:admin` (the person picks the project), `project:<id>:read|write|admin`
(a specific project), `sql:read`, `sql:write`, `migrations:write`,
`functions:deploy`, `branches:write`, `keys:secret`. The person can grant
less than was requested, never more.

```sh
curl -X POST "$SCRIBASE_API_URL/v1/oauth/device/code" \
  -d client_id=scribase-cli \
  --data-urlencode 'client_name=Claude Code' \
  --data-urlencode 'scope=project:write sql:write migrations:write'
```

**Response `200`:**

```json
{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "SCRB-7F3K-Q2MX",
  "verification_uri": "https://console.scribase.com/device",
  "verification_uri_complete": "https://console.scribase.com/device?user_code=SCRB-7F3K-Q2MX",
  "expires_in": 600,
  "interval": 5
}
```

User codes use only unambiguous characters (no `0`/`O`, `1`/`I`/`L`), and the
console accepts them with or without the `SCRB-` prefix, dashes or capitals.
Keep `device_code` private to the polling process; show the person only the
URL and `user_code`. Creation is rate limited per client address
(`429` with `Retry-After`).

## POST /v1/oauth/token

Anonymous. Poll no faster than `interval` seconds.

| Field | Value |
|---|---|
| `grant_type` | `urn:ietf:params:oauth:grant-type:device_code` |
| `device_code` | From the step above |
| `client_id` | Optional, the same as above |

While waiting, and on failure, the answer is `400` with an OAuth error:

| `error` | Meaning | What the client does |
|---|---|---|
| `authorization_pending` | Nobody has approved yet | Poll again after `interval` |
| `slow_down` | Polled too fast | Add 5 seconds to the interval (the response carries the new `interval`) |
| `access_denied` | The person clicked Deny | Stop |
| `expired_token` | Ten minutes passed | Start over |
| `invalid_grant` | Unknown code, or its token was already issued | Stop |
| `unsupported_grant_type` | Wrong `grant_type` | Fix the request |

Once approved, the next poll answers `200`, exactly once:

```json
{
  "access_token": "scb_agt_1p-rw-sqlw-mig-x2609260412_3f9a...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "project:web:write sql:write migrations:write",
  "organization_id": "acme",
  "project_id": "web",
  "token_id": "7d1e..."
}
```

The token is an ordinary [agent token](https://docs.scribase.com/docs/agents/safety.md): bound to the
organization, limited to the approved scopes, listed, audited and revocable
under **Account > Access tokens**. A second poll with the same `device_code`
gets `invalid_grant`.

## Console routes

These back the console's `/device` page. They need a signed-in console
session; agent tokens are refused.

### POST /v1/oauth/device/lookup

`{ "user_code": "SCRB-7F3K-Q2MX" }` returns the pending request: client name,
requested scopes, the address it came from, when it was made and when it
expires. Lookups are rate limited per person, so codes cannot be guessed.

### POST /v1/oauth/device/approve

| Field | Notes |
|---|---|
| `user_code` | The code shown by the agent |
| `organization_id` | You must be a member |
| `project_id` | A project in that organization, or `*` for every project |
| `level` | `read`, `write` or `admin`, at most what was requested |
| `capabilities` | Subset of the requested `sql:read`, `sql:write`, `migrations:write`, `functions:deploy`, `branches:write`, `keys:secret` |
| `ttl` | 1 hour to 30 days: `1h`, `8h` (default), `24h`, `7d`, `30d` |

### POST /v1/oauth/device/deny

`{ "user_code": "SCRB-7F3K-Q2MX" }`. The agent's next poll gets
`access_denied`.

Every approval and denial is recorded: who, which client, from which
address, which scopes, and the id of the token that was issued.

---

Source: https://docs.scribase.com/docs/api/environment-keys

# Environment API keys

Each environment has its own keys. Apps pass them to `supabase-js` (or any
Supabase client) when they call the environment's `/auth/v1`, `/rest/v1`,
`/storage/v1`, `/realtime/v1` and `/functions/v1` endpoints. They are different
from the [access tokens and organization API keys](https://docs.scribase.com/docs/api/tokens.md) that call
the `/v1` control API.

| Key | Format | Who may hold it |
|---|---|---|
| `anon` | HS256 JWT, role `anon` | Anyone. Safe in an app bundle; row-level security decides what it can read |
| `publishable_key` | `sb_publishable_...` | Same as `anon`. The new-style opaque form |
| `service_role` | HS256 JWT, role `service_role` | Servers only. Bypasses row-level security |
| `secret_key` | `sb_secret_...` | Servers only. The opaque form of `service_role` |

All four derive from one JWT secret per environment. The JWTs have a fixed
issue time and a ten-year expiry, so they stay the same until the secret is
rotated, like Supabase project keys. The gateway (or, on the single box, the
project router) swaps an opaque key for its JWT on the way in, so current
`supabase-js` versions work with either style. An opaque key the environment
did not issue gets `401`.

## Where to find them

- **Console**: the environment's **API keys** page.
- **CLI**: [`scribase apps switch`](https://docs.scribase.com/docs/cli/apps.md) prints the URL and the
  `anon` or publishable key for an app. It never prints the server keys.
- **API**: the route below.

## GET .../environments/{env}/api-keys

`GET /v1/organizations/{org}/projects/{project}/environments/{env}/api-keys`

```json
{
  "organization_id": "acme",
  "project_id": "my-app",
  "environment_id": "production",
  "api_url": "https://<label>.<domain>",
  "anon_key": "eyJ...",
  "jwt_secret_version": 1,
  "jwt_secret_source": "control_plane",
  "publishable_key": "sb_publishable_...",
  "service_role_key": "eyJ...",
  "secret_key": "sb_secret_..."
}
```

- `service_role_key` and `secret_key` are `null` for **viewers**.
- `api_url` is `null` when the control plane has no public gateway URL
  configured.
- `?reveal=jwt_secret` adds the raw `jwt_secret`. It mints any token for the
  environment, so it needs the owner or admin role and, on an account with an
  authenticator app, a fresh MFA code.

```sh
curl "$SCRIBASE_API_URL/v1/organizations/acme/projects/my-app/environments/production/api-keys" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN"
```

## POST .../environments/{env}/api-keys/rotate

`POST /v1/organizations/{org}/projects/{project}/environments/{env}/api-keys/rotate`

Replaces the environment's JWT secret. This **invalidates the old `anon`,
`service_role`, publishable and secret keys and every session token** the
environment issued, so every client needs the new keys and every user signs in
again. The response has the same shape as `GET`, with the new keys and a higher
`jwt_secret_version`. The control plane then publishes the new secret to the
environment's services and rolls them out.

- Needs the owner or admin role and, on an account with an authenticator app, a
  fresh MFA code.
- A personal access token cannot answer an MFA challenge, so on such accounts
  revealing and rotating are console-only. CI can still read the `anon` and
  `service_role` keys, which are never MFA-gated, or use a service-account
  machine token.
- `409 jwt_secret_operator_managed`: the deployment signs every environment
  with one operator-managed secret (`SCRIBASE_TENANT_JWT_SECRET`). Rotate it
  there instead.

## Keys after an import

`scribase import supabase` never copies the source project's keys or JWT
secret. The environment keeps its own keys, so the two projects never trust
each other's tokens. Users keep their ids and passwords and sign in once more.

---

Source: https://docs.scribase.com/docs/api/organizations

# Organizations

An organization is the top-level tenant container in Scribase. It holds
projects, members, environments, and the audit log. All resource paths are
scoped under an organization ID.

## Organization ID rules

- Lowercase alphanumeric and hyphens only.
- 2–64 characters.
- Must start and end with an alphanumeric character.

## Endpoints

### PUT /v1/organizations/{organization_id}

Create or update an organization.

**Request body:**

```json
{ "display_name": "Acme Platform" }
```

**Response `200 OK`:**

```json
{
  "id": "acme",
  "display_name": "Acme Platform",
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase org put acme "Acme Platform"
```

---

### GET /v1/organizations/{organization_id}

Read an organization record.

**Response `200 OK`:**

```json
{
  "id": "acme",
  "display_name": "Acme Platform",
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Example:**

```sh
scribase org get acme
```

---

## Memberships

Members are subjects (user IDs or service account IDs from your OIDC provider)
with an assigned role.

### PUT /v1/organizations/{organization_id}/memberships

Add or update a member's role.

**Request body:**

```json
{ "subject": "user|abc123", "role": "developer" }
```

**Roles:**

| Role | Permissions |
|---|---|
| `owner` | Full control, including deleting the organization |
| `admin` | Manage projects and environments |
| `developer` | Create and manage environments |
| `viewer` | Read-only access |

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase member put acme "user|abc123" developer
```

---

## Audit events

See [Audit Events](https://docs.scribase.com/docs/api/audit.md) for the organization audit log.

---

Source: https://docs.scribase.com/docs/api/projects

# Projects

A project is a logical grouping of environments within an organization. For
example, a single organization might have a `billing` project and a `platform`
project, each with `production`, `staging`, and per-PR preview environments.

## Endpoints

### PUT /v1/organizations/{org}/projects/{project_id}

Create or update a project.

**Request body:**

```json
{ "region": "us-east", "postgres_major": 17 }
```

**Response `200 OK`:**

```json
{
  "organization_id": "acme",
  "project_id": "store",
  "region": "us-east",
  "postgres_major": 17,
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase project put acme store us-east
```

---

### GET /v1/organizations/{org}/projects/{project_id}

Read a project record.

**Response `200 OK`:**

```json
{
  "organization_id": "acme",
  "project_id": "store",
  "region": "us-east",
  "postgres_major": 17,
  "created_at": "2026-01-01T00:00:00Z"
}
```

**Example:**

```sh
scribase project get acme store
```

---

## Regions

Regions identify where Scribase provisions managed Postgres environments. For
self-hosted deployments, the region is a label you define — it has no
infrastructure meaning beyond identifying which node or datacenter the
environment runs on.

Examples: `us-east`, `eu-1`, `ap-southeast-2`.

## Notes

- Project IDs follow the same rules as organization IDs: lowercase alphanumeric + hyphens, 2–64 characters.
- `postgres_major` must be `17` (the only supported version in the current release).
- A project cannot be deleted while it has active environments.

---

Source: https://docs.scribase.com/docs/api/environments

# Environments

An environment is a Postgres database (and its associated application services)
that Scribase provisions and manages. Each environment belongs to a project and
has a kind, a data mode, and a lifecycle managed through the control-plane API.

## Environment kinds

| Kind | Description |
|---|---|
| `production` | Long-lived, serves live traffic |
| `staging` | Long-lived pre-production environment |
| `preview` | Short-lived, typically one per pull request. Carries `ttl_hours` and is swept when it expires. |

## Data modes

| Mode | Description |
|---|---|
| `snapshot` | Cloned from the source environment's data |
| `sanitized` | Cloned, with sensitive columns and secrets scrubbed — the default for previews |
| `schema_only` | The schema with no rows |

---

## Endpoints

### POST /v1/environments

Create an environment. Returns `202 Accepted` with an operation to poll.

**Request body:**

```json
{
  "organization_id": "acme",
  "project_id": "store",
  "environment_id": "production",
  "kind": "production",
  "data_mode": "snapshot",
  "region": "us-east",
  "postgres_major": 17,
  "ttl_hours": null
}
```

`ttl_hours` is optional and only meaningful for `preview` environments. Set it
to have the environment automatically deleted after N hours.

**Response `202 Accepted`:**

```json
{
  "id": "op_01J...",
  "kind": "create_environment",
  "environment": { "organization_id": "acme", "project_id": "store", "environment_id": "production" },
  "state": "pending",
  "attempt_count": 0
}
```

**Headers required:** `Idempotency-Key`

**Example:**

```sh
scribase env create acme store production production snapshot us-east create-prod-001
# Preview with 72-hour TTL
scribase env create acme store pr-42 preview sanitized us-east create-pr42-001 72
```

---

### GET /v1/organizations/{org}/projects/{project}/environments/{env}

Read an environment record.

**Response `200 OK`:**

```json
{
  "organization_id": "acme",
  "project_id": "store",
  "environment_id": "production",
  "kind": "production",
  "data_mode": "snapshot",
  "region": "us-east",
  "phase": "ready",
  "postgres_major": 17
}
```

Preview environments also carry `ttl_hours` and `expires_at_epoch_seconds`.
The connection string is not part of the record; read it from the
`connection` endpoint below.

**Example:**

```sh
scribase env get acme store production
```

---

### POST /v1/organizations/{org}/projects/{project}/environments/{env}/suspend

Suspends a running environment. Returns `202 Accepted`.

**Headers required:** `Idempotency-Key`

```sh
scribase env suspend acme store production suspend-001
```

---

### POST /v1/organizations/{org}/projects/{project}/environments/{env}/resume

Resumes a suspended environment. Returns `202 Accepted`.

**Headers required:** `Idempotency-Key`

```sh
scribase env resume acme store production resume-001
```

---

### DELETE /v1/organizations/{org}/projects/{project}/environments/{env}

Deletes an environment. Returns `202 Accepted`. Deletion is permanent.

**Headers required:** `Idempotency-Key`

```sh
scribase env delete acme store production delete-001
```

---

### POST /v1/organizations/{org}/projects/{project}/environments/{env}/renew

Extend a preview's lifetime to `ttl_hours` from now, without recreating it.
Returns `200 OK` with the renewed expiry.

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/pr-42/renew" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ttl_hours": 48}'
```

`ttl_hours` must be a positive integer; `0` is rejected with `invalid_ttl`.

---

### GET /v1/organizations/{org}/projects/{project}/environments/{env}/connection

Returns the environment's Postgres connection URI as
`{"connection_uri": "postgresql://..."}`. This is a server-to-server endpoint:
keep the URI out of browsers and logs.

---

### GET /v1/organizations/{org}/projects/{project}/environments/{env}/usage

The environment's flat-price usage envelope: the plan, its flat price, the
billing period, each hard cap with current use, and any capacity packs.

---

## Environment lifecycle

`phase` moves through:

```
requested → provisioning → ready ⟷ suspended
                 ↓            ↓
        failed_recoverable  updating → ready
                              ↓
                          deleting → deleted
```

All state transitions are asynchronous. Poll the operation returned by each
mutating call until `state` is `succeeded`, `failed`, or `cancelled`.

---

## Listing

`GET /v1/environments` lists an organization's environments as
`{"environments": [...]}`.

| Parameter | Description |
|---|---|
| `organization_id` | Organization to list (required) |
| `project_id` | Narrow to one project (optional) |
| `limit` | 1–200, default 100 |

---

Source: https://docs.scribase.com/docs/api/backups

# Backups & restore

Every environment has durable backup records. A backup is a PostgreSQL
custom-format archive whose readability is checked with `pg_restore --list` and
whose bytes are fingerprinted with SHA-256. A restore replays a backup into a
target environment and records **evidence**: how many relations and
RLS-protected relations were restored, and the SHA-256 of the evidence record —
so "the backup works" is something you can read, not assume.

Archives are produced by the `scribase-backup` operator tool (see
[Self-hosting](https://docs.scribase.com/docs/self-hosting.md)); these routes manage the records, trigger
new backups, and run restores.

---

## GET /v1/organizations/{org}/projects/{project}/environments/{env}/backups

Lists the environment's backups, newest first. Optional `?limit=` (1–200).

```json
{
  "items": [
    {
      "backup_id": "nightly-2026-09-23",
      "environment": { "organization_id": "acme", "project_id": "store", "environment_id": "production" },
      "status": "available",
      "format": "custom",
      "size_bytes": 482133504,
      "created_at_epoch_seconds": 1790121600,
      "sha256": "9f2b...",
      "object": { "bucket": "scribase-backups", "key": "scribase/acme/store/production/9f2b....dump", "uploaded_at_epoch_seconds": 1790121900 },
      "verified_at_epoch_seconds": 1790122200
    }
  ]
}
```

`status` is `pending`, `available`, `failed`, or `deleted`. `sha256`, `object`,
and `verified_at_epoch_seconds` appear once the archive exists, is uploaded, and
is verified.

## POST /v1/organizations/{org}/projects/{project}/environments/{env}/backups

Records a new pending backup. The `Idempotency-Key` header becomes the backup
ID, so retrying the same request never creates a second backup.

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/backups" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: manual-2026-09-23' \
  -d '{}'
```

## GET /v1/organizations/{org}/projects/{project}/backups/{backup_id}?environment={env}

Reads one backup. A backup ID is unique within its environment, so the
environment is a required query parameter.

## POST /v1/organizations/{org}/projects/{project}/backups/{backup_id}/restore?environment={env}

Restores the backup from `env` into `target_environment_id` in the same
project. **Headers required:** `Idempotency-Key`.

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/backups/nightly-2026-09-23/restore?environment=production" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: restore-drill-2026-09-23' \
  -d '{"target_environment_id": "restore-drill"}'
```

**Response:**

```json
{
  "id": "rst_...",
  "source": { "organization_id": "acme", "project_id": "store", "environment_id": "production" },
  "target": { "organization_id": "acme", "project_id": "store", "environment_id": "restore-drill" },
  "source_backup_id": "nightly-2026-09-23",
  "status": "restored",
  "created_at_epoch_seconds": 1790125000,
  "relation_count": 64,
  "rls_relation_count": 18,
  "evidence_sha256": "c41a...",
  "restored_at_epoch_seconds": 1790125410
}
```

`status` is `pending`, `restored`, or `failed`. The evidence fields are present
once the restore has completed.

Restore into a separate environment first (a *restore drill*), check the
evidence and your application against it, then promote — never restore over
production blind.

---

## SDK

```ts
const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' };

const backups = await scribase.backups.list(ref);
const backup = await scribase.backups.create(ref, { backupId: 'manual-2026-09-23' });
const { restore } = await scribase.restores.start(ref, {
  backupId: 'nightly-2026-09-23',
  targetEnvironmentId: 'restore-drill',
});
```

## Console

Each environment's **Backups** page lists backups with their verification
state and starts restores.

---

Source: https://docs.scribase.com/docs/api/exports

# Exports

An export is not a SQL dump. It is a bundle that **boots**: the database
archive, storage objects, auth users, and policies, rendered as a Docker
Compose project or Kustomize manifests, with a manifest of SHA-256 digests over
every artifact and an optional HMAC-SHA256 signature — so you can verify the bundle before
you trust it.

---

## POST /v1/organizations/{org}/projects/{project}/environments/{env}/exports

Queues a bundle for the environment. The export worker dumps, packs and
boot-checks it in the background; poll
`GET /v1/organizations/{org}/exports/{export_id}` until `state` is `available`.

| Field | Type | Notes |
|---|---|---|
| `format` | `"compose"` or `"kustomize"` | Render target for the bundle (default `compose`) |
| `include_data` | boolean | Include table data in the database archive (default `true`) |
| `include_storage` | boolean | Include storage objects (default `true`) |

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/exports" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"format": "compose"}'
```

**Response:** the export record, in state `requested`:

```json
{
  "export_id": "ex-3f9a1c2b7d4e5f60",
  "project": { "organization_id": "acme", "project_id": "store" },
  "source_environment_id": "production",
  "state": "requested",
  "format": "compose",
  "include_data": true,
  "include_storage": true,
  "created_at_epoch_seconds": 1790125000,
  "total_size_bytes": 0,
  "sha256": "",
  "postgres_major": 0,
  "artifacts": [],
  "boots_elsewhere": false,
  "storage_object_count": 0
}
```

`state` moves through `requested`, `packing` and `verifying` to `available`
(or `failed`, with an `error`). An available export also carries
`expires_at_epoch_seconds` and a signed `download_url`.

## POST /v1/organizations/{org}/projects/{project}/export

The project-scoped form. Name the source environment in the body:

```json
{ "source_environment_id": "production", "format": "kustomize" }
```

`format` defaults to `compose`.

## GET /v1/organizations/{org}/projects/{project}/exports

The project's persisted export manifests as `{"items": [...]}`.

## GET /v1/organizations/{org}/exports

Every export in the organization, newest first, as `{"items": [...]}`.

## GET /v1/organizations/{org}/exports/{export_id}

One export record. Once `state` is `available` it includes `download_url`, a
short-lived signed link.

## GET /v1/organizations/{org}/exports/{export_id}/download?expires=...&signature=...

Streams the gzip bundle. The link carries its own authorization (an HMAC over
the organization, export and expiry), so it needs no bearer header; request a
fresh one with the route above when it expires.

---

## CLI

```sh
scribase export create acme store production --format compose --wait --out store.tar.gz
scribase export list acme store
scribase export download acme ex-3f9a1c2b7d4e5f60 --out store.tar.gz
```

See [`scribase export`](https://docs.scribase.com/docs/cli/export.md).

## SDK

```ts
const { manifest } = await scribase.export.create(
  { organizationId: 'acme', projectId: 'store', environmentId: 'production' },
  { format: 'compose' },
);
```

---

Source: https://docs.scribase.com/docs/api/migrations

# Migrations

The migrations endpoint accepts a set of migrations, lints them, and optionally
applies them to an environment. The lint step is always performed first —
`apply: false` is the safe default for reviewing a migration plan before
committing it.

## Endpoint

### POST /v1/organizations/{org}/projects/{project}/environments/{env}/migrations

**Request body:**

```json
{
  "migrations": [
    {
      "version": "1",
      "name": "init",
      "up": "CREATE TABLE orders (id uuid primary key);",
      "down": "DROP TABLE orders;"
    },
    {
      "version": "2",
      "name": "add_user_id",
      "up": "ALTER TABLE orders ADD COLUMN user_id uuid NOT NULL;"
    }
  ],
  "apply": false
}
```

Set `apply: true` to execute the migrations after lint passes.

**Response `200 OK` (lint only):**

```json
{
  "plan": [
    {
      "version": "1",
      "name": "init",
      "direction": "up",
      "findings": []
    },
    {
      "version": "2",
      "name": "add_user_id",
      "direction": "up",
      "findings": [
        {
          "severity": "warning",
          "message": "Adding a NOT NULL column without a default to a large table may cause a full rewrite."
        }
      ]
    }
  ],
  "applied": false
}
```

**Response `200 OK` (applied):**

```json
{
  "plan": [...],
  "applied": true,
  "applied_at": "2026-01-01T12:00:00Z"
}
```

## Lint findings

| Severity | Meaning |
|---|---|
| `error` | Migration will fail or cause data loss. Blocked — `apply` cannot proceed. |
| `warning` | Migration may cause problems at scale or violate best practices. |
| `info` | Informational note. |

## Migration version ordering

Migrations are ordered by their `version` field parsed as a number. The server
applies them in ascending order and skips already-applied versions.

## CLI shortcut

```sh
# Lint only
scribase migrate acme store production --dir ./migrations

# Apply
scribase migrate acme store production --dir ./migrations --apply
```

See [scribase migrate](https://docs.scribase.com/docs/cli/migrate.md) for directory and file formats.

---

Source: https://docs.scribase.com/docs/api/branches

# Branches

Branches register environments as forks of a parent environment for schema
diffing and merging. A branch captures the parent's schema as a merge base,
enabling safe three-way merges and clean PR workflows.

## Endpoints

### POST /v1/organizations/{org}/projects/{project}/branches

Register an environment as a branch.

**Request body:**

```json
{
  "environment_id": "pr-42",
  "base_environment_id": "production"
}
```

`base_environment_id` is optional. When omitted, the branch has no merge base
(useful for standalone review environments).

**Response `200 OK`:**

```json
{
  "environment_id": "pr-42",
  "base_environment_id": "production",
  "merge_base_schema_version": "abc123",
  "registered_at": "2026-01-01T00:00:00Z"
}
```

---

### GET /v1/organizations/{org}/projects/{project}/branches

List all registered branches.

**Response `200 OK`:**

```json
{
  "branches": [
    {
      "environment_id": "pr-42",
      "base_environment_id": "production",
      "registered_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

---

### POST /v1/organizations/{org}/projects/{project}/branches/diff

Compute the schema diff between two environments.

**Request body:**

```json
{ "base": "production", "head": "pr-42" }
```

**Response `200 OK`:**

```json
{
  "changes": [
    {
      "kind": "table",
      "name": "payments",
      "action": "added",
      "definition": "CREATE TABLE payments (...)"
    },
    {
      "kind": "column",
      "table": "orders",
      "name": "paid_at",
      "action": "added",
      "definition": "timestamptz"
    }
  ]
}
```

---

### POST /v1/organizations/{org}/projects/{project}/branches/merge

Merge the head environment's schema into the base environment.

**Request body:**

```json
{ "base": "production", "head": "pr-42", "force": false }
```

With `force: false`, the merge fails if there are conflicts. With `force: true`,
the head schema wins on all conflicts.

**Response `200 OK`:**

```json
{
  "merged": true,
  "changes": [...],
  "conflicts": []
}
```

---

### POST /v1/organizations/{org}/projects/{project}/branches/{env}/pr

Link a branch to a pull request.

**Request body:**

```json
{
  "provider": "github",
  "repository": "acme/store",
  "number": 42,
  "url_template": null
}
```

Supported providers: `github`, `gitlab`, `bitbucket`, `generic`.

For `generic`, provide `url_template` with `{repo}` and `{number}` placeholders:

```json
{
  "provider": "generic",
  "repository": "acme/store",
  "number": 42,
  "url_template": "https://git.example.com/{repo}/pull/{number}"
}
```

---

## CLI shortcuts

```sh
scribase branch register acme store pr-42 --base production
scribase branch diff acme store production pr-42
scribase branch merge acme store production pr-42
scribase branch pr acme store pr-42 github acme/store 42
scribase branch list acme store
```

See [scribase branch](https://docs.scribase.com/docs/cli/branch.md) for the full local and remote branch reference.

---

Source: https://docs.scribase.com/docs/api/queues

# Queues

Scribase environments include a durable message queue primitive backed by
Postgres. Queues are created per-environment and support at-least-once delivery
with visibility timeouts.

## Endpoint

All queue operations use a single route:

```
POST /v1/organizations/{org}/projects/{project}/environments/{env}/queues/{queue}
```

The action travels in the request body.

---

## Actions

### create

Create a new queue.

**Request body:**

```json
{ "action": "create" }
```

**Response `200 OK`:**

```json
{ "queue": "events", "created": true }
```

---

### send

Send a message. The `message` field must be valid JSON.

**Request body:**

```json
{
  "action": "send",
  "message": { "type": "order.placed", "id": 42 },
  "delay_seconds": 0
}
```

`delay_seconds` is optional (default: 0). The message becomes visible after the delay.

**Response `200 OK`:**

```json
{ "msg_id": 12345 }
```

---

### read

Read one or more messages. Messages become invisible during the visibility
timeout — other readers will not see them.

**Request body:**

```json
{
  "action": "read",
  "quantity": 1,
  "visibility_timeout_seconds": 30
}
```

**Response `200 OK`:**

```json
{
  "messages": [
    {
      "msg_id": 12345,
      "message": { "type": "order.placed", "id": 42 },
      "enqueued_at": "2026-01-01T00:00:00Z",
      "read_count": 1
    }
  ]
}
```

---

### archive

Archive a message after processing. The message is retained for audit.

**Request body:**

```json
{ "action": "archive", "msg_id": 12345 }
```

**Response `200 OK`:**

```json
{ "archived": true }
```

---

### delete

Permanently delete a message.

**Request body:**

```json
{ "action": "delete", "msg_id": 12345 }
```

**Response `200 OK`:**

```json
{ "deleted": true }
```

---

### purge

Delete all messages in the queue.

**Request body:**

```json
{ "action": "purge" }
```

**Response `200 OK`:**

```json
{ "purged_count": 42 }
```

---

## Delivery semantics

- **At-least-once delivery:** A message is re-delivered if it is not archived
  or deleted within its visibility timeout.
- **Ordering:** Messages are returned roughly in FIFO order but strict ordering
  is not guaranteed under concurrent readers.
- **`read_count`:** The number of times a message has been delivered. Use this
  to detect poison messages and route them to a dead-letter queue.

---

Source: https://docs.scribase.com/docs/api/imports

# Imports

The imports endpoint migrates a live Supabase project (or a Firebase or
InstantDB export) into a Scribase environment. It reads the source project's schema, data, auth users, and storage
objects and applies them to the destination environment.

## Endpoint

### POST /v1/imports

**Request body:**

```json
{
  "sourceProjectRef": "abcdefghijkl",
  "sourceConnectionString": "postgresql://postgres:pass@db.abcdef.supabase.co:5432/postgres",
  "sourceServiceKey": "eyJhbGci...",
  "destination": {
    "organizationId": "acme",
    "projectId": "store",
    "environmentId": "production"
  },
  "dryRun": false
}
```

Set `dryRun: true` to receive a plan of what would be migrated without
touching anything. `source` selects the importer (`supabase` by default, or
`firebase` / `instantdb` with an export).

Optional fields:

| Field | Description |
|---|---|
| `sourceSchemas` | Array of schema names to copy. Default: every application schema (everything that is not a Supabase/Postgres system schema and not owned by an extension). |
| `includeStorage` | `false` skips buckets and objects (default `true`). |
| `targetStorageUrl` + `targetServiceKey` | The destination environment's storage API (`https://<label>.<domain>/storage/v1`) and its `service_role` key, used to upload object bytes. `scribase import supabase` fills both from the environment's API keys. Without them the control plane's `SCRIBASE_TENANT_STORAGE_ENDPOINT` / `SCRIBASE_TENANT_SERVICE_KEY` apply. |
| `verifyLogin` | `{ "email" }` for a structural login proof, `{ "email", "password" }` for a live one. |

**Headers:** `Idempotency-Key` (optional; a retry with the same key returns the
run it already started instead of starting a second one).

**Dry run — `200 OK`:** the plan.

```json
{
  "projectRef": "abcdefghijklmnopqrst",
  "destination": "acme/store/production",
  "planned": { "tables": 14, "rows": 82341, "authUsers": 1201, "objects": 421, "...": 0 },
  "tables": ["public.orders", "public.customers"],
  "findings": [{ "category": "edge_functions", "severity": "action", "detail": "..." }]
}
```

**Full run — `202 Accepted`:** the request is validated (a bad body or source
fails here with a 4xx, before anything is read), the import starts in the
background, and the response carries its `import_id` at once. The `Location`
header points at the progress route.

```json
{
  "import_id": "im-3f2a9c...",
  "status": "running",
  "phase": "schema",
  "phases": ["schema", "auth_users", "data", "policies", "storage_objects", "edge_functions", "secrets", "verify", "done"],
  "organization_id": "acme",
  "project_id": "store",
  "environment_id": "production",
  "source": "supabase",
  "source_ref": "abcdefghijklmnopqrst",
  "counts": { "tables": 0, "rows": 0, "authUsers": 0, "objects": 0, "...": 0 },
  "findings": 0,
  "errors": [],
  "resumable": false,
  "attempts": 1,
  "started_at": 1790000000,
  "updated_at": 1790000000
}
```

Each control-API replica runs at most `SCRIBASE_IMPORT_MAX_RUNNING` imports at
once (default 4); past that the route answers `429 import_capacity`.

### GET /v1/imports/{import_id}

The run's progress, in the same shape: `status` (`running`, `succeeded`,
`failed`, `interrupted`), the `phase` in progress, `counts` moved so far
(cumulative across resumes), the number of `findings`, `errors`
(`[{code, detail}]`), `resumable`, `attempts`, and `heartbeat_at` (the running
replica's last liveness signal). Once it has succeeded the body adds `passed`
(the fail-closed parity verdict), the full `report`, and `report_recorded`,
which says whether the report was stored in the import history under the same
id (`GET /v1/organizations/{org}/imports/{import_id}`).

Progress is stored in the control-plane database (`scribase.import_jobs`,
migration `0017`) after every committed step, so any replica answers a poll and
a restart loses nothing. Source credentials are never stored: they stay inside
the process running the import.

A run whose replica stopped (crash, restart, rollout) becomes `interrupted`
with an `import_interrupted` error: at control-API start for runs an earlier
process on the same host owned, and on any replica once the run's heartbeat is
older than `SCRIBASE_IMPORT_STALE_SECONDS` (default 120). The durable store uses
`SCRIBASE_IMPORTS_REGISTRY_DATABASE_URL`, falling back to
`SCRIBASE_CONTROL_PLANE_ADMIN_DATABASE_URL`; with neither set, progress is kept
in memory only and a restart loses in-flight runs.

### POST /v1/imports/{import_id}/resume

Continues an `interrupted` run (or one that `failed` with a transient error)
from its last committed step. Completed phases are not re-run; every step
upserts on the destination, so the step in flight when the run stopped is
replayed safely. Send the original `POST /v1/imports` body again: the
credentials were never stored, and the destination and source must match the
run (`409 import_resume_mismatch` otherwise).

Tables without a single-column primary key have nothing to upsert on, so they
are handled differently: before the first page of such a table is written, the
importer records the destination table's row count in the checkpoint, and on
every later page (including a replayed one) it skips the rows that already
landed. The source is read in a total order (by the whole row) so a page holds
the same rows on every read. A replayed page on a keyless table therefore does
not insert duplicates, provided nothing else writes to that destination table
while the import runs; if something does, the report carries a warning for
that table.

| Answer | Meaning |
|---|---|
| `202` | The run restarted; poll `GET /v1/imports/{import_id}` |
| `200` | The run is already running (a retried resume never starts a second copy) |
| `409 import_finished` | It succeeded; nothing to resume |
| `409 import_not_resumable` | No step committed before it stopped, or it failed on an invalid request or checkpoint; start a new import |

The CLI (`scribase import supabase ...`) and the console wizard follow this
route automatically; `--no-wait` prints the started run and returns.

## Report fields

The finished `report` carries:

| Field | Description |
|---|---|
| `moved` | What moved: tables, rows, auth users, identities, MFA factors, policies, buckets, objects, bytes |
| `findings` | Items that need an operator (edge functions to redeploy, secrets to re-enter) |
| `verdict` | `VERIFIED`, `MISMATCH`, or `UNVERIFIED` (fail-closed) |
| `verified` | `true` only when every parity check passed |
| `failures` | The checks that did not pass |
| `verification` | Per-check results and per-table source/target row counts and checksums |

## Verification checks

After a full run, Scribase proves the copy before calling it done: per-table
row counts and checksums, RLS policy parity, auth-user and object counts, and
(when requested with `verifyLogin`) a sign-in for a known user.

## Security

The source connection string and service key are secrets. Use environment
variable overrides or a secret manager rather than hardcoding them in scripts:

```sh
export SCRIBASE_SOURCE_CONNECTION_STRING="postgresql://..."
export SCRIBASE_SOURCE_SERVICE_KEY="eyJ..."
```

The CLI passes them to `curl` through stdin, never in process arguments.

---

Source: https://docs.scribase.com/docs/api/operations

# Operations

Mutating environment endpoints return `202 Accepted` with an operation record.
Poll this endpoint until the operation reaches a terminal state.

## Endpoint

### GET /v1/operations/{operation_id}

Read an operation's current state.

**Headers required:** `X-Scribase-Organization-ID: <org-id>`

**Response `200 OK`:**

```json
{
  "id": "op-01J...",
  "kind": "create_environment",
  "state": "running",
  "organization_id": "acme",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:05Z",
  "result": null,
  "error": null
}
```

## Operation states

| State | Terminal | Description |
|---|---|---|
| `pending` | No | Queued, not yet started |
| `running` | No | In progress |
| `succeeded` | Yes | Completed successfully |
| `failed` | Yes | Completed with an error |

## Operation kinds

| Kind | Triggered by |
|---|---|
| `create_environment` | `POST /v1/environments` |
| `delete_environment` | `DELETE .../environments/{env}` |
| `suspend_environment` | `POST .../environments/{env}/suspend` |
| `resume_environment` | `POST .../environments/{env}/resume` |
| `run_migrations` | `POST .../environments/{env}/migrations` with `apply: true` |
| `import` | `POST /v1/imports` |

## Polling

```sh
scribase operation get acme op-01J...
```

Poll every few seconds until `state` is `succeeded` or `failed`. The SDK's
`operations.wait()` handles polling automatically:

```ts
const { operation } = await scribase.environments.create({ ... });
const result = await scribase.operations.wait(operation.id, 'acme');
```

## Error details

When `state` is `failed`, the `error` field carries a human-readable reason:

```json
{
  "id": "op_01J...",
  "kind": "create_environment",
  "state": "failed",
  "attempt_count": 3,
  "error": "provider rejected the environment: region us-east is at capacity"
}
```

Errors returned by the request itself (as opposed to a failed operation) use
the Problem Details format described in the [API overview](https://docs.scribase.com/docs/api.md).

## CLI

```sh
scribase operation get acme op-01J...
```

---

Source: https://docs.scribase.com/docs/api/audit

# Audit Events

Every mutating API call leaves an immutable audit event in the organization's
audit log. Events are retained indefinitely and paginated by cursor.

## Endpoint

### GET /v1/organizations/{org}/audit-events

**Query parameters:**

| Parameter | Description |
|---|---|
| `after` | Cursor — the numeric event ID to start after (for pagination) |
| `limit` | Number of events to return. Must be 1–200 (default: 50) |

**Response `200 OK`:**

```json
{
  "events": [
    {
      "id": 1042,
      "organization_id": "acme",
      "actor": "user|abc123",
      "action": "create_environment",
      "resource_kind": "environment",
      "resource_id": "production",
      "occurred_at": "2026-01-01T12:00:00Z",
      "metadata": {
        "project_id": "store",
        "kind": "production",
        "data_mode": "snapshot"
      }
    }
  ],
  "next_cursor": 1043
}
```

When `next_cursor` is `null`, there are no more events.

## Audited actions

| Action | Description |
|---|---|
| `put_organization` | Organization created or updated |
| `put_member` | Member role added or changed |
| `put_project` | Project created or updated |
| `create_environment` | Environment provisioned |
| `delete_environment` | Environment deleted |
| `suspend_environment` | Environment suspended |
| `resume_environment` | Environment resumed |
| `run_migrations` | Migrations applied |
| `register_branch` | Branch registered |
| `merge_branch` | Branch merged |
| `import` | Supabase import executed |

## CLI

```sh
# Latest 50 events
scribase audit list acme

# Paginate: events after cursor 1000, up to 100
scribase audit list acme 1000 100
```

## Notes

- Audit events are append-only and cannot be modified or deleted.
- The `actor` field contains the OIDC subject of the API caller.
- `metadata` varies by action — it records the key parameters of the call.

---

Source: https://docs.scribase.com/docs/api/data-plane

# Data-plane views

These routes let the console, the SDK, and agents look inside a running
environment without holding its database credentials. All are scoped under:

```
/v1/organizations/{org}/projects/{project}/environments/{env}
```

and require a Bearer token with access to the organization. When a service is
unreachable or not yet deployed, the list routes return an empty result with a
`notes` explanation instead of an error.

| Method & path (relative) | Returns | SDK |
|---|---|---|
| `GET /auth/users` | Auth users | `auth.listUsers(ref)` |
| `GET /auth/providers` | Configured sign-in providers | `auth.listProviders(ref)` |
| `GET /auth/policies` | Row-level security policies | `auth.listPolicies(ref)` |
| `GET /database/tables` | `public` tables, columns, and access rules | `database.tables(ref)` |
| `POST /database/query` | Result of one read-only statement (`SELECT`, `WITH`, `EXPLAIN`) | — |
| `GET /storage/buckets` | Buckets | `storage.listBuckets(ref)` |
| `GET /storage/buckets/{bucket}/objects` | Objects in a bucket | `storage.listObjects(ref, bucket)` |
| `GET /functions` | Deployed edge functions | `functions.list(ref)` |
| `POST /functions` | Deploy (create or replace) a function: `{"name", "source"}` | `functions.deploy(ref, {...})` |
| `POST /functions/{name}/invoke` | Invoke a function with a JSON payload | `functions.invoke(ref, name, payload)` |
| `GET /realtime/channels` | Active realtime channels | `realtime.channels(ref)` |
| `GET /queues` | Queues and their depth | `queues.list(ref)` |
| `GET /queues/{queue}/messages` | Messages waiting in a queue (not consumed) | `queues.peek(ref, queue)` |
| `GET /metrics` | Connection, query, and storage metrics | `metrics.get(ref)` |
| `GET /insights` | Analyzed findings with remediations | `insights.get(ref)` |
| `GET /logs` | Recent service log lines, newest first (`limit`, `level`, `from`) | `environments.logs(ref)` |
| `GET /usage` | Flat-price usage envelope | `usage.get(ref)` |

## Read-only queries

`POST /database/query` runs a single statement inside a bounded read-only
transaction and returns capped rows, or the plan for `EXPLAIN`. Writes and DDL
are rejected before execution and again by the database itself. Use
[migrations](https://docs.scribase.com/docs/api/migrations.md) to change schema.

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/database/query" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "select count(*) from orders"}'
```

---

Source: https://docs.scribase.com/docs/sdk

# SDK — scribase-js

`scribase` is the typed, fetch-based TypeScript client for the Scribase `/v1`
control-plane API. Every resource is a property on the client, mutations take an
idempotency key (one is minted for you when omitted), and transient failures
(429, 503, network errors) are retried with exponential backoff.

It runs anywhere `fetch` exists: Node.js 22.13+, Deno, Bun, and edge runtimes.

## Installation

> **Not yet published.** The `scribase` package is not on the npm registry yet,
> so `npm install scribase` does not work today. Until it is published, build it
> from the repository (`packages/scribase-js`) and install it from a local path
> or tarball:
>
> ```sh
> cd packages/scribase-js && npm install && npm run build && npm pack
> npm install /path/to/scribase-<version>.tgz   # in your app
> ```

Once the package is published, the install is:

```sh
npm install scribase
# or
pnpm add scribase
```

## Credentials

The client needs two things:

| Option | Where it comes from |
|---|---|
| `baseUrl` | `https://api.scribase.com` for hosted Scribase, or your own gateway when self-hosted |
| `token` | A personal access token (console **Account → Access tokens**) or an organization API key (console **Organization → API tokens**). See [Access tokens & API keys](https://docs.scribase.com/docs/api/tokens.md). |

Keep the token in an environment variable or secret manager, never in source.

## Quick start

```ts
import { ScribaseClient } from 'scribase';

const scribase = new ScribaseClient({
  baseUrl: process.env.SCRIBASE_API_URL ?? 'https://api.scribase.com',
  token: process.env.SCRIBASE_ACCESS_TOKEN ?? '',
});

// Create an environment — returns an accepted operation
const { operation } = await scribase.environments.create({
  organization_id: 'acme',
  project_id: 'store',
  environment_id: 'production',
  kind: 'production',
  data_mode: 'snapshot',
  region: 'us-east',
  postgres_major: 17,
});

// Wait until it is terminal (throws OperationFailedError on failure)
await scribase.operations.wait(operation.id, 'acme');
```

Most environment-scoped calls take an `EnvironmentRef`:

```ts
const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' };
```

Project-scoped calls (branches, project exports) take a `ProjectRef`:
`{ organizationId, projectId }`.

## Client options

```ts
const scribase = new ScribaseClient({
  baseUrl: 'https://api.scribase.com',

  // A string, or a (possibly async) provider called before every request
  token: async () => await readTokenFromVault(),

  timeoutMs: 30_000,        // per-attempt timeout (default 30s)
  maxRetries: 3,            // retries for 429/503/network failures (default 3)
  retryBaseDelayMs: 250,    // backoff base delay (default 250ms)
  retryMaxDelayMs: 20_000,  // ceiling for one backoff wait (default 20s)
  defaultHeaders: { 'X-Request-Source': 'deploy-bot' },
  userAgent: 'my-app/1.0',
});
```

## Organizations, members, and projects

```ts
await scribase.organizations.put('acme', { display_name: 'Acme Inc.' });
const org = await scribase.organizations.get('acme');
const orgs = await scribase.organizations.list();

await scribase.organizations.putMembership('acme', { subject: 'user:ada', role: 'developer' });
const members = await scribase.organizations.listMemberships('acme');

await scribase.projects.put('acme', 'store', { region: 'us-east', postgres_major: 17 });
const project = await scribase.projects.get('acme', 'store');
const projects = await scribase.projects.list('acme');
```

Roles are `owner`, `admin`, `developer`, and `viewer`.

## Environments

```ts
const env = await scribase.environments.get(ref);

// List every environment in an org (optionally one project); returns an array
const environments = await scribase.environments.list({ organizationId: 'acme', projectId: 'store' });

// Lifecycle transitions return accepted operations
const { operation } = await scribase.environments.suspend(ref, { idempotencyKey: 'suspend-prod-001' });
await scribase.operations.wait(operation.id, 'acme');
await scribase.environments.resume(ref);
await scribase.environments.delete(ref);

// Server-side only: the Postgres connection URI
const { connection_uri } = await scribase.environments.connection(ref);

// Recent service logs, newest first
const logs = await scribase.environments.logs(ref, { limit: 100, level: 'error' });
```

`kind` is `production`, `staging`, or `preview`; `data_mode` is `snapshot`,
`sanitized`, or `schema_only`.

## Previews

Previews are TTL-swept environments of kind `preview`. The resource defaults the
data mode to `sanitized` and always sets a TTL (24 hours unless you pass one):

```ts
const { operation } = await scribase.previews.create({
  organizationId: 'acme',
  projectId: 'store',
  environmentId: 'pr-1487',
  region: 'us-east',
  postgres_major: 17,
  ttlHours: 72,
});
await scribase.operations.wait(operation.id, 'acme');

const previews = await scribase.previews.list({ organizationId: 'acme', projectId: 'store' });

const pr = { organizationId: 'acme', projectId: 'store', environmentId: 'pr-1487' };
await scribase.previews.renew(pr, 48);            // extend to 48h from now
const preview = await scribase.previews.get(pr);
scribase.previews.remainingSeconds(preview);       // seconds until the sweep, or null
await scribase.previews.delete(pr);
```

## Backups and verified restore

```ts
// Newest first
const backups = await scribase.backups.list(ref, { limit: 20 });

// Record a new backup; its id is the idempotency key (minted when omitted)
const backup = await scribase.backups.create(ref, { backupId: 'nightly-2026-09-23' });

const one = await scribase.backups.get(ref, 'nightly-2026-09-23');
console.log(one.status, one.sha256, one.verified_at_epoch_seconds);

// Restore a backup into a target environment in the same project
const { restore } = await scribase.restores.start(ref, {
  backupId: 'nightly-2026-09-23',
  targetEnvironmentId: 'restore-drill',
});
console.log(restore.status); // 'pending' | 'restored' | 'failed'
```

Once a restore reaches `restored` it carries its evidence — the number of
relations and RLS-protected relations restored, and the SHA-256 of the evidence
record. `restoreEvidence(restore)` returns it as a typed object, or `null` if the
restore has not completed:

```ts
import { restoreEvidence } from 'scribase';

const evidence = restoreEvidence(restore);
```

## Export

Build a runnable, signed bundle of an environment:

```ts
const { manifest, bundleRef } = await scribase.export.create(ref, { format: 'compose' });
console.log(manifest.database.sha256, manifest.artifacts.length, bundleRef);

// Project-scoped form: name the source environment in the request
await scribase.export.createForProject(
  { organizationId: 'acme', projectId: 'store' },
  { sourceEnvironmentId: 'production', format: 'kustomize' },
);

const exports = await scribase.export.list({ organizationId: 'acme', projectId: 'store' });
const saved = await scribase.export.getManifest('acme', manifest.bundle_id);
```

## Migrations

```ts
const migrations = [
  { version: '1', name: 'init', up: 'create table orders (id bigint primary key);' },
  { version: '2', name: 'add_total', up: 'alter table orders add column total numeric;', down: 'alter table orders drop column total;' },
];

// Plan and lint only — nothing executes
const planned = await scribase.migrations.plan(ref, migrations);
if (planned.lintFindings.some((finding) => finding.severity === 'BLOCK')) {
  throw new Error('migration blocked by lint');
}

// Apply
const result = await scribase.migrations.run(ref, { migrations, apply: true });
console.log(result.applied);
```

## Branches

```ts
const project = { organizationId: 'acme', projectId: 'store' };

await scribase.branches.register(project, {
  environment_id: 'pr-1487',
  base_environment_id: 'production',
});

const branches = await scribase.branches.list(project);
const diff = await scribase.branches.diff(project, { base: 'production', head: 'pr-1487' });
const merge = await scribase.branches.merge(project, { base: 'production', head: 'pr-1487', force: false });

await scribase.branches.linkPullRequest(project, 'pr-1487', {
  provider: 'github',
  repository: 'acme/storefront',
  number: 1487,
});
```

## Queues

```ts
await scribase.queues.create(ref, 'events');
const { msg_id } = await scribase.queues.send(ref, 'events', { type: 'order.created' }, { delaySeconds: 5 });

// read() returns an array of messages and hides them for the visibility timeout
const messages = await scribase.queues.read(ref, 'events', { quantity: 10, visibilityTimeoutSeconds: 30 });
for (const message of messages) {
  await scribase.queues.archive(ref, 'events', message.msg_id);
}

const queues = await scribase.queues.list(ref);          // with current depth
const waiting = await scribase.queues.peek(ref, 'events'); // look without consuming
await scribase.queues.purge(ref, 'events');
```

## Imports from Supabase

```ts
const request = {
  sourceProjectRef: 'abcd1234',
  sourceConnectionString: process.env.SOURCE_PG_URL ?? '',
  sourceServiceKey: process.env.SOURCE_SERVICE_KEY ?? '',
  destination: { organizationId: 'acme', projectId: 'store', environmentId: 'production' },
};

// Plan first — nothing is written
const plan = await scribase.imports.dryRun(request);
console.log(plan.planned.tables, plan.planned.authUsers, plan.findings);

// Then move it
const report = await scribase.imports.create(request);
console.log(report.moved, report.verification?.checks);

// History and a stored report
const history = await scribase.imports.history('acme');
```

The source credentials are used once and never returned.

## Edge functions

```ts
import { readFile } from 'node:fs/promises';

const source = await readFile('functions/hello/index.ts', 'utf8');
await scribase.functions.deploy(ref, { name: 'hello', source });

const { functions } = await scribase.functions.list(ref);
const { result } = await scribase.functions.invoke<{ hello: string }>(ref, 'hello', { name: 'world' });
```

Function names are letters, digits, hyphens, or underscores. See
[Functions](https://docs.scribase.com/docs/concepts/functions.md) for writing and running functions.

## Operations

```ts
const op = await scribase.operations.get('op_01J...', 'acme');

await scribase.operations.wait('op_01J...', 'acme', {
  intervalMs: 2000,       // poll interval (default 1000)
  timeoutMs: 600_000,     // give up after (default 300000)
  onUpdate: (snapshot) => console.log(snapshot.state),
  throwOnFailure: true,   // default true
});
```

## Usage, billing, and audit

```ts
const usage = await scribase.usage.get(ref);                  // flat-price envelope and caps
const nearing = await scribase.usage.capsNearingLimit(ref, 0.8);
const billing = await scribase.usage.billing('acme');

const events = await scribase.audit.list('acme', { limit: 50 });

// Or iterate every page
for await (const event of scribase.audit.paginate('acme')) {
  console.log(event);
}
```

## Account and credentials

```ts
const me = await scribase.account.get();
const tokens = await scribase.account.listTokens();
const created = await scribase.account.createToken({ name: 'ci', expires_in_days: 90 });
console.log(created.token); // shown once — store it now
await scribase.account.revokeToken(created.id);

const key = await scribase.organizations.createApiKey('acme', { name: 'deploy-bot', scopes: ['deploy'] });
await scribase.organizations.revokeApiKey('acme', key.api_key_id);
```

## Read-only views into a live environment

```ts
const users = await scribase.auth.listUsers(ref);
const providers = await scribase.auth.listProviders(ref);
const policies = await scribase.auth.listPolicies(ref);

const tables = await scribase.database.tables(ref);

const buckets = await scribase.storage.listBuckets(ref);
const objects = await scribase.storage.listObjects(ref, 'avatars');

const channels = await scribase.realtime.channels(ref);
const metrics = await scribase.metrics.get(ref);
const insights = await scribase.insights.get(ref);
```

## Error handling

Every error extends `ScribaseError`. HTTP failures are `ScribaseApiError`
subclasses keyed by status, carrying the problem+json `code` and `detail`:

```ts
import {
  ConflictError,
  NetworkError,
  NotFoundError,
  OperationFailedError,
  QuotaExceededError,
  TimeoutError,
} from 'scribase';

try {
  const { operation } = await scribase.environments.create({ /* ... */ });
  await scribase.operations.wait(operation.id, 'acme');
} catch (error) {
  if (error instanceof QuotaExceededError) {
    console.error('Plan cap reached — add a capacity pack or free a slot');
  } else if (error instanceof OperationFailedError) {
    console.error('Provisioning failed', error);
  } else if (error instanceof NetworkError || error instanceof TimeoutError) {
    console.error('Could not reach the API');
  } else {
    throw error;
  }
}
```

## Idempotency keys

Mutating calls accept `idempotencyKey`. When omitted the SDK mints one per call;
pass your own to make a retried job safe across processes:

```ts
import { newIdempotencyKey } from 'scribase';

const key = newIdempotencyKey();
await scribase.environments.suspend(ref, { idempotencyKey: key });
await scribase.environments.suspend(ref, { idempotencyKey: key }); // replay, not a second suspend
```

Keys are 8–128 printable ASCII characters. A replayed request returns the
original response, and the result's `idempotencyReplayed` flag is `true`.

---

Source: https://docs.scribase.com/docs/concepts/auth

# Auth

Scribase includes a full-featured authentication service built on
[GoTrue](https://github.com/supabase/gotrue) — the same battle-tested service
that powers Supabase. Every environment gets its own isolated auth instance.

## How it works

1. A client signs in through GoTrue (email/password, OAuth, SAML, magic link,
   phone OTP).
2. GoTrue issues a signed JWT containing `sub` (user ID), `email`, and custom
   claims.
3. The JWT is sent with data-plane API calls (`Authorization: Bearer <token>`).
4. Postgres row-level security policies use `auth.uid()` and `auth.jwt()` to
   enforce per-row access control.

## Endpoints

All auth calls go to the gateway path `/auth/v1/...`:

| Endpoint | Description |
|---|---|
| `POST /auth/v1/signup` | Create a new user |
| `POST /auth/v1/token?grant_type=password` | Sign in with email + password |
| `GET /auth/v1/authorize?provider=github` | Start OAuth flow |
| `POST /auth/v1/token?grant_type=refresh_token` | Refresh an access token |
| `POST /auth/v1/logout` | Revoke session |
| `GET /auth/v1/user` | Get the current user |

## JWT structure

```json
{
  "sub": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "email": "alice@example.com",
  "role": "authenticated",
  "aud": "authenticated",
  "exp": 1775000000,
  "iat": 1774996400,
  "app_metadata": {
    "provider": "github"
  },
  "user_metadata": {
    "full_name": "Alice"
  }
}
```

## Using auth in RLS policies

Access the current user's ID and claims inside Postgres:

```sql
-- auth.uid() returns the `sub` claim as a uuid
-- auth.jwt() returns the full decoded token as jsonb

CREATE POLICY "users can read their own data"
  ON profiles FOR SELECT
  USING (id = auth.uid());

CREATE POLICY "admin role only"
  ON admin_logs FOR SELECT
  USING ((auth.jwt() ->> 'role') = 'admin');
```

The Scribase schema language lets you declare these inline:

```scribase
model profiles {
  id         uuid primary key default auth.uid()
  email      text not null
  created_at timestamptz not null default now()

  policy "owner can read" on select
    using (id = auth.uid())

  policy "owner can update" on update
    using (id = auth.uid())
    with check (id = auth.uid())
}
```

## Providers

Configure providers in the environment's `auth` service settings:

| Provider | Type | Notes |
|---|---|---|
| Email / Password | Built-in | Always available |
| Magic Link | Built-in | Requires SMTP |
| OAuth (GitHub, Google, GitLab, ...) | OAuth 2.0 | Requires app credentials |
| SAML 2.0 | Enterprise SSO | Requires IdP metadata |
| Phone OTP | SMS | Requires Twilio or similar |

## Admin API

The auth admin API (at `/auth/v1/admin/...`) requires the service-role JWT
and allows creating, listing, and managing users server-side:

```ts
const { users } = await scribase.auth.listUsers(ref);
```

## Local development

`scribase dev` starts the auth service automatically. It uses the local
`JWT_SECRET` and `ANON_KEY` configured in `.scribase/`. You can override
these in the `SCRIBASE_DEV_*` environment variables.

---

Source: https://docs.scribase.com/docs/concepts/storage

# Storage

Every Scribase environment includes an S3-compatible object storage service
backed by `storage-api`. Buckets, access policies, and object lifecycle are all
managed within the environment.

## Concepts

| Term | Description |
|---|---|
| **Bucket** | A named container for objects. Each environment can have many buckets. |
| **Object** | A file stored in a bucket, identified by a key (path). |
| **Bucket policy** | Public or private; controls anonymous access to the bucket. |
| **RLS policy** | Postgres-enforced per-object access control for authenticated users. |

## HTTP API

The storage API is accessible at `/storage/v1/`:

| Endpoint | Description |
|---|---|
| `POST /storage/v1/bucket` | Create a bucket |
| `GET /storage/v1/bucket` | List buckets |
| `GET /storage/v1/bucket/{id}` | Get bucket details |
| `DELETE /storage/v1/bucket/{id}` | Delete bucket |
| `POST /storage/v1/object/{bucket}/{path}` | Upload an object |
| `GET /storage/v1/object/{bucket}/{path}` | Download an object |
| `DELETE /storage/v1/object/{bucket}/{path}` | Delete an object |
| `GET /storage/v1/object/list/{bucket}` | List objects |
| `POST /storage/v1/object/sign/{bucket}/{path}` | Generate a signed URL |

### Creating a bucket

```sh
curl -X POST 'https://<your-project-url>/storage/v1/bucket' \
  -H 'Authorization: Bearer <service-role-key>' \
  -H 'Content-Type: application/json' \
  -d '{"id": "avatars", "name": "avatars", "public": false}'
```

### Uploading a file

```sh
curl -X POST 'https://<your-project-url>/storage/v1/object/avatars/user-123.png' \
  -H 'Authorization: Bearer <user-jwt>' \
  -H 'Content-Type: image/png' \
  --data-binary @avatar.png
```

## RLS policies for storage

Storage objects are backed by the `storage.objects` table. Protect them with
RLS policies:

```sql
-- Allow a user to access their own objects
CREATE POLICY "owner can upload"
  ON storage.objects FOR INSERT
  WITH CHECK (bucket_id = 'avatars' AND (storage.foldername(name))[1] = auth.uid()::text);

CREATE POLICY "owner can read"
  ON storage.objects FOR SELECT
  USING (bucket_id = 'avatars' AND (storage.foldername(name))[1] = auth.uid()::text);
```

## Signed URLs

Generate time-limited signed URLs for objects without requiring authentication
on the client:

```sh
curl -X POST 'https://<your-project-url>/storage/v1/object/sign/avatars/user-123.png' \
  -H 'Authorization: Bearer <service-role-key>' \
  -H 'Content-Type: application/json' \
  -d '{"expiresIn": 3600}'
```

## SDK

```ts
// List buckets
const { buckets } = await scribase.storage.listBuckets(ref);

// List objects in a bucket
const objects = await scribase.storage.listObjects(ref, 'avatars', {
  prefix: 'user-123/',
  limit: 100,
});
```

## Local development

`scribase dev` starts the storage service automatically. Files are stored
locally under `.scribase/storage/`. No S3 credentials are required for local
development.

---

Source: https://docs.scribase.com/docs/concepts/realtime

# Realtime

Scribase Realtime provides WebSocket subscriptions over Postgres logical
replication. Clients subscribe to table changes, broadcast messages, or track
presence — all through a single WebSocket connection.

## Channels

A **channel** is a named subscription topic. Three channel types are supported:

| Type | Description |
|---|---|
| `postgres_changes` | Subscribe to INSERT/UPDATE/DELETE on a Postgres table |
| `broadcast` | Pub/sub message passing between clients |
| `presence` | Track which clients are online in a channel |

## Subscribing to database changes

```ts
import { createClient } from '@supabase/supabase-js';

const scribase = createClient(
  'https://<your-project-url>',
  '<anon-key>'
);

scribase
  .channel('orders')
  .on(
    'postgres_changes',
    { event: '*', schema: 'public', table: 'orders' },
    (payload) => {
      console.log('Change received!', payload);
    }
  )
  .subscribe();
```

The `event` filter can be `'*'`, `'INSERT'`, `'UPDATE'`, or `'DELETE'`.

## Row-level filtering

Subscriptions respect RLS policies — clients only receive changes for rows
their JWT is authorized to see.

You can also add a `filter` string for server-side filtering:

```ts
.on('postgres_changes', {
  event: 'INSERT',
  schema: 'public',
  table: 'messages',
  filter: 'channel_id=eq.42',
}, handler)
```

## Broadcast

Send messages to all subscribers of a channel without touching the database:

```ts
const channel = scribase.channel('room:42');

channel.on('broadcast', { event: 'typing' }, (payload) => {
  console.log(payload.userId, 'is typing');
});

await channel.subscribe();

// Send
channel.send({ type: 'broadcast', event: 'typing', payload: { userId: 'alice' } });
```

## Presence

Track which clients are currently subscribed to a channel:

```ts
const channel = scribase.channel('room:42');

channel.on('presence', { event: 'sync' }, () => {
  const state = channel.presenceState();
  console.log('Online users:', state);
});

await channel.subscribe();
await channel.track({ user: 'alice', online_at: new Date().toISOString() });
```

## RLS and security

- Realtime respects your Postgres RLS policies. A subscriber only receives
  events for rows they can SELECT.
- For public events (no auth), use a public table or an open policy.
- The anon key authorizes subscriptions as the anonymous role.

## HTTP API (management)

The realtime management API is accessible via the SDK:

```ts
const { channels } = await scribase.realtime.listChannels(ref);
```

## Local development

`scribase dev` starts the Realtime service automatically. Connect to:

```
ws://localhost:8000/realtime/v1/websocket?apikey=<anon-key>
```

---

Source: https://docs.scribase.com/docs/concepts/functions

# Functions

Scribase edge functions are server-side TypeScript or JavaScript modules that
run on the open-source Deno [edge-runtime](https://github.com/supabase/edge-runtime)
— the same runtime Supabase uses — next to your database. They are served on
the Supabase-compatible `/functions/v1/<name>` path, so existing function code
and the clients that call it move over by changing the URL and keys.

## Writing a function

A function is a directory with an `index.ts` that serves requests:

```ts
// functions/hello/index.ts
Deno.serve(async (req: Request) => {
  const { name } = await req.json();
  return Response.json({ message: `Hello, ${name}!` });
});
```

## Environment available to a function

Every function receives the Supabase-compatible variables plus every secret set
on its environment (see Secrets below):

| Variable | Value |
|---|---|
| `SUPABASE_URL` | The environment's public API URL |
| `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` | The environment's API keys |
| `SUPABASE_DB_URL` | The Postgres connection string (`scribase dev` also sets `DATABASE_URL` and `SCRIBASE_DB_URL`) |
| Your secrets | Each secret set with `scribase secrets set` or the console, by name |

The JWT signing secret and the runtime's own admin credential are never passed
to a deployed function. To verify a caller, forward their `Authorization`
header to auth (`supabase.auth.getUser(token)`) rather than checking the
signature yourself.

Query Postgres directly with any Deno Postgres driver:

```ts
import postgres from 'https://deno.land/x/postgresjs@v3.4.4/mod.js';

const sql = postgres(Deno.env.get('SUPABASE_DB_URL')!);

Deno.serve(async () => {
  const orders = await sql`select id, total from orders order by id desc limit 10`;
  return Response.json({ orders });
});
```

Or use supabase-js against your environment's API:

```ts
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';

const client = createClient(Deno.env.get('SUPABASE_URL')!, Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!);
```

## Deploying to a hosted environment

With the CLI, point `functions deploy` at the function's directory. It sends
`index.ts`, every sibling module (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.mts`,
`.json`) and an `import_map.json` if one is present, as one bundle:

```sh
scribase functions deploy acme store production hello ./functions/hello
scribase functions deploy acme store production hello ./functions/hello --import-map ./import_map.json
```

Each deploy is a new immutable version. The runtime boots it once and makes it
active only if the boot succeeds; otherwise the previous version keeps serving
and the command fails with the boot error. Manage versions with:

```sh
scribase functions list     acme store production
scribase functions get      acme store production hello [--version 3]
scribase functions rollback acme store production hello 3
scribase functions delete   acme store production hello
scribase functions invoke   acme store production hello --data '{"name":"Alice"}'
```

From CI without the CLI, send the function's name and source to the
environment's functions route. A deploy creates or replaces the function; a runtime that
rejects it surfaces a real error rather than a silent success.

```sh
jq -n --arg source "$(cat functions/hello/index.ts)" '{name: "hello", source: $source}' \
  | curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/functions" \
      -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
      -H 'Content-Type: application/json' --data-binary @-
```

With the SDK:

```ts
import { readFile } from 'node:fs/promises';

const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' };
await scribase.functions.deploy(ref, {
  name: 'hello',
  source: await readFile('functions/hello/index.ts', 'utf8'),
});
```

Function names are letters, digits, hyphens, or underscores, starting with a
letter or digit.

## Logs

Each function's log holds one line per invocation (method, path, status,
duration) plus the function's own output: `console.log`, `console.info`,
`console.warn` and `console.error`, uncaught exceptions, and CPU, wall-clock or
memory limit terminations. Read it on the function's page in the console or
with:

```sh
scribase functions logs acme store production hello --limit 50
```

Lines are also shipped to the environment's logs page, where they are kept
after the runtime restarts.

## Listing and invoking through the control API

```ts
const { functions, notes } = await scribase.functions.list(ref);
const { result } = await scribase.functions.invoke(ref, 'hello', { name: 'Alice' });
```

```sh
curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/production/functions/hello/invoke" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Alice"}'
```

`list` degrades to an empty array with a `notes` explanation if the runtime is
unreachable, so a dashboard never breaks; `invoke` and `deploy` surface errors.

## Calling a function from your app

Clients call functions on the compatible path, with a user's JWT or the anon key:

```sh
curl -X POST 'https://<your-environment-api-url>/functions/v1/hello' \
  -H 'Authorization: Bearer <anon-key-or-user-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Alice"}'
```

With supabase-js: `await supabase.functions.invoke('hello', { body: { name: 'Alice' } })`.

## Local development

`scribase dev` starts the edge-runtime (port `9000` by default) with
`<SCRIBASE_HOME>/functions/main` as its main service — `.scribase/functions/main`
unless you set `SCRIBASE_HOME`. The main service is a small router that maps
`/<name>` to a sibling function directory. Create it once:

```ts
// .scribase/functions/main/index.ts
declare const EdgeRuntime: {
  userWorkers: {
    create(options: Record<string, unknown>): Promise<{ fetch(req: Request): Promise<Response> }>;
  };
};

const FUNCTIONS_ROOT = new URL('..', import.meta.url).pathname.replace(/\/$/, '');

Deno.serve(async (req) => {
  const segments = new URL(req.url).pathname.split('/').filter(Boolean);
  // Accept both /hello and /functions/v1/hello.
  const name = segments[0] === 'functions' && segments[1] === 'v1' ? segments[2] ?? '' : segments[0] ?? '';
  if (!/^[A-Za-z0-9_-]+$/.test(name)) {
    return Response.json({ error: 'invalid function name' }, { status: 400 });
  }
  try {
    const worker = await EdgeRuntime.userWorkers.create({
      servicePath: `${FUNCTIONS_ROOT}/${name}`,
      memoryLimitMb: 150,
      workerTimeoutMs: 30_000,
      envVars: Object.entries(Deno.env.toObject()),
    });
    return await worker.fetch(req);
  } catch {
    return Response.json({ error: `function "${name}" is not deployed` }, { status: 404 });
  }
});
```

Then put each function next to it and start the stack:

```
.scribase/functions/
├── main/
│   └── index.ts      # the router above
└── hello/
    └── index.ts
```

```sh
scribase dev --services functions
curl -X POST http://localhost:9000/hello -H 'Content-Type: application/json' -d '{"name":"Alice"}'
```

The self-hosted Docker Compose stack ships the same router at
`deploy/compose/functions/main/index.ts`.

## Secrets

Values your function needs beyond the injected variables, such as third-party
API keys, are environment secrets. They are encrypted at rest, bound into every
function in the environment, and read with `Deno.env.get('NAME')`:

```sh
scribase secrets set   acme store production STRIPE_KEY --from-env STRIPE_KEY
printf %s "$WEBHOOK_SECRET" | scribase secrets set acme store production WEBHOOK_SECRET --stdin
scribase secrets list  acme store production
scribase secrets unset acme store production STRIPE_KEY
```

Prefer `--from-env` or `--stdin` over a literal value so the secret stays out of
your shell history. Secrets can also be managed on the environment's Secrets
page in the console.

Setting, rotating or removing a secret reaches deployed functions without a
redeploy: the next request after the change boots a fresh worker with the new
values, while requests already in flight finish on the old one.

## CORS

Return CORS headers from functions called by browsers:

```ts
const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'authorization, content-type',
};

Deno.serve(async (req) => {
  if (req.method === 'OPTIONS') {
    return new Response('ok', { headers: corsHeaders });
  }
  return Response.json({ ok: true }, { headers: corsHeaders });
});
```

---

Source: https://docs.scribase.com/docs/concepts/branching

# Branching

Scribase branching gives every developer, feature branch, and pull request its
own database that forks from production in under a second. Branches are cheap,
isolated, and disposable.

## Local branches

Local branches use copy-on-write Postgres snapshots inside `.scribase/`.

```sh
# Create a branch from the primary
scribase branch new my-feature

# Connect to it
psql "$(scribase branch url my-feature)"

# List all branches
scribase branch list

# Delete when done
scribase branch delete my-feature
```

Copy-on-write means: only the pages you write are copied. A branch that makes
a small schema change uses almost no extra disk space.

## Remote branches (control-plane)

Remote branches are registered environments linked to a parent for schema
diffing and merging. They are the building block for pull-request preview
environments.

### PR preview workflow

```sh
# 1. Provision a preview environment
scribase env create acme store pr-42 preview schema-only us-east create-pr-42 72

# 2. Register it as a branch of production
scribase branch register acme store pr-42 --base production

# 3. Link it to the GitHub PR
scribase branch pr acme store pr-42 github acme/store 42

# 4. Apply the branch's migrations
scribase migrate acme store pr-42 --dir ./migrations --apply

# 5. Review the schema diff
scribase branch diff acme store production pr-42

# 6. Merge on approval
scribase branch merge acme store production pr-42
```

## Branch data modes

When creating a preview environment, choose a data mode:

| Mode | Description |
|---|---|
| `schema-only` | Empty database with production schema applied |
| `snapshot` | Cloned from the latest production backup |
| `empty` | Completely blank Postgres instance |

`schema-only` is the fastest and most common for PR previews. `snapshot` is
better when tests need realistic data.

## TTL (time-to-live)

Preview environments can be auto-deleted after N hours:

```sh
scribase env create acme store pr-42 preview schema-only us-east create-pr-42 72
#                                                                               ^^ 72-hour TTL
```

When the TTL expires, the operator's reconcile loop (the `worker` service) claims the preview and deletes it through the same audited delete operation as `scribase env delete`. Extend a preview before it expires with `scribase env renew`.

## Merge conflict resolution

A three-way merge compares the base environment's schema at registration time
(the merge base), the current base (production), and the head (the branch).

- **No conflict**: the changes apply cleanly.
- **Conflict**: both sides modified the same object. Use `--force` to have the
  head win, or resolve manually.

```sh
scribase branch merge acme store production pr-42 --force
```

## Schema diff output

`branch diff` returns a list of changed objects:

```json
{
  "changes": [
    { "kind": "table", "name": "payments", "action": "added" },
    { "kind": "column", "table": "orders", "name": "paid_at", "action": "added" },
    { "kind": "policy", "table": "payments", "name": "owner can read", "action": "added" }
  ]
}
```

## Best practices

- Create one branch per feature or PR, not per developer.
- Use `schema-only` mode for CI test branches to avoid copying production data.
- Set a short TTL (24–72 hours) on preview environments to avoid accumulating
  stale branches.
- Always run `branch diff` before merging to review what changed.
- Run `schema test` against the branch before merging to catch policy regressions.

---

Source: https://docs.scribase.com/docs/concepts/sso

# Single sign-on (SSO)

An organization can connect its own identity provider (IdP) so members sign in
to the console through it. Scribase supports **OpenID Connect** (Okta, Microsoft
Entra ID, Google Workspace, Auth0, Keycloak, and any other OIDC provider) and
**SAML 2.0**. Owners and admins configure it in the console under
**Single sign-on**, or through the [API](#api).

## How sign-in works

1. On the sign-in page, a person chooses **Sign in with your company (SSO)** and
   enters their work email.
2. The email's domain must be verified by an organization with SSO enabled.
   The browser goes to that organization's IdP.
3. The IdP sends the browser back to the control API, which validates the
   response, then back to the console, which receives a session bound to that
   organization.

Who the person becomes in Scribase:

- **A linked account.** An administrator who runs the connection test links
  their IdP identity to their existing account and keeps their role.
- **An invitation.** If there is a pending invitation for the email address,
  signing in through the IdP accepts it with the invited role.
- **An automatic join.** If the email is on a verified domain and automatic
  join is on, the person joins with the chosen role (developer or viewer).
- Anyone else is refused with a message to ask an administrator for an
  invitation.

A session from SSO lasts 12 hours by default and only works for the
organization whose IdP issued it.

## Set up OIDC

1. At your IdP, create a web application (confidential client) and register
   the **redirect URI** shown in the console:
   `https://<api>/v1/sso/oidc/callback`.
2. Allow the `openid`, `email`, and `profile` scopes.
3. In the console, choose **OpenID Connect** and enter the issuer URL, client ID,
   and client secret. Scribase checks the issuer's discovery document when you
   save. The client secret is stored encrypted and never shown again.

The sign-in uses the authorization-code flow with PKCE and a nonce. The ID
token's signature is verified against the provider's published keys (RS256,
PS256, ES256, and EdDSA are accepted), along with its issuer, audience, expiry,
and nonce. An email the provider marks as unverified is ignored.

## Set up SAML 2.0

1. At your IdP, create a SAML application with:
   - **ACS URL** (HTTP-POST): `https://<api>/v1/sso/saml/<org>/acs`
   - **Entity ID / audience**: `https://<api>/v1/sso/saml/<org>/metadata`
     (this URL also serves the SP metadata document)
   - **Name ID**: the user's email address (or send an `email` attribute)
   - **Signing**: sign the assertion or the response with RSA-SHA256
   - **Encryption**: off
2. In the console, choose **SAML 2.0** and paste the IdP metadata XML, or enter
   the IdP entity ID, its single sign-on URL (HTTP-Redirect binding), and its
   signing certificate.

Every response is checked before anything in it is used: the XML signature
against your certificate (exclusive canonicalization, SHA-256 or SHA-512; SHA-1
is refused), exactly one assertion, the issuer, the audience, the recipient,
the `InResponseTo` link to the sign-in Scribase started, and the validity
window. Sign-ins started at the IdP (IdP-initiated SSO) are not supported:
start from the Scribase sign-in page.

## Verify your domains

Add each email domain your people use, then publish the TXT record the console
shows:

| Name | Type | Value |
|---|---|---|
| `_scribase-sso.example.com` | TXT | `scribase-sso-verification=<token>` |

Choose **Verify** once the record is live. A domain can be verified by one
organization. Only verified domains route sign-ins to your IdP and allow
automatic joins.

## Test, then require SSO

**Test connection** signs you in at the IdP without changing your session. A
passing test links your IdP identity to your account and records that these
exact settings work. Changing the IdP settings later clears the result.

**Require SSO** can only be turned on after a passing test against the current
settings. While it is on:

- Everyone except **owners** must use an SSO session for this organization.
  Owners are exempt so a broken IdP can never lock the organization out.
- Personal access tokens stop working in this organization for non-owners.
  Organization API keys keep working; use them for CI and automation.

To change the IdP while SSO is required, save the new settings with the
requirement off, run the test, and turn it back on.

## API

All configuration routes need an owner or admin (reading needs any member).

| Route | Purpose |
|---|---|
| `GET /v1/organizations/{org}/sso` | Connection, domains, and the values to register at the IdP |
| `PUT /v1/organizations/{org}/sso` | Create or replace the connection |
| `DELETE /v1/organizations/{org}/sso` | Remove it and end all SSO sessions |
| `POST /v1/organizations/{org}/sso/domains` | Claim a domain |
| `POST /v1/organizations/{org}/sso/domains/{domain}/verify` | Check its TXT record |
| `DELETE /v1/organizations/{org}/sso/domains/{domain}` | Release it |
| `POST /v1/organizations/{org}/sso/test` | Start a connection test |
| `POST /v1/sso/start` | Begin sign-in for an email |
| `POST /v1/sso/exchange` | Redeem the one-time code for a session or test result |
| `POST /v1/sso/logout` | End an SSO session |

Configuration changes, domain verification, sign-ins, and automatic joins are
written to the organization's [audit log](https://docs.scribase.com/docs/api/audit.md).

Self-hosting needs `SCRIBASE_PUBLIC_API_URL` and a few optional settings; see
[Self-hosting](https://docs.scribase.com/docs/self-hosting.md#organization-single-sign-on-optional).

---

Source: https://docs.scribase.com/docs/aegis

# Aegis Policy Compiler

Aegis is the Scribase policy compiler and test harness. It verifies that your
row-level security policies do what you intend before they reach production.

## The problem Aegis solves

Postgres RLS policies are SQL expressions evaluated at runtime. A policy bug
— a typo, a wrong column reference, a missing `WITH CHECK` — silently passes
syntax checking but causes data leaks or access denials at runtime.

Aegis turns policy correctness into a compile-time property by letting you
write tests alongside your schema and run them in CI.

## Policy syntax in schemas

Declare policies inline with your model:

```scribase
model orders {
  id         uuid primary key default gen_random_uuid()
  user_id    uuid not null references auth.users
  status     text not null default 'pending'
  total      numeric(12,2) not null

  policy "owner can read" on select
    using (auth.uid() = user_id)

  policy "owner can insert" on insert
    with check (auth.uid() = user_id)

  policy "owner can update" on update
    using (auth.uid() = user_id)
    with check (auth.uid() = user_id and status != 'paid')

  policy "service role has full access" on all
    using (auth.role() = 'service_role')
    with check (auth.role() = 'service_role')
}
```

## Writing policy tests

Tests declare a JWT context and assert what the authenticated user can and
cannot do:

```scribase
test "order owner can read their own order" {
  as user { uid: "user-alice" }
  expect select from orders where user_id = "user-alice" to succeed
}

test "order owner cannot read another user's order" {
  as user { uid: "user-alice" }
  expect select from orders where user_id = "user-bob" to return empty
}

test "unauthenticated user cannot insert" {
  as anon
  expect insert into orders { user_id: "user-alice", total: 99 } to fail
}

test "owner cannot update paid order" {
  as user { uid: "user-alice" }
  given orders { id: "ord-1", user_id: "user-alice", status: "paid", total: 99 }
  expect update orders set status = "pending" where id = "ord-1" to fail
}

test "service role can read all orders" {
  as service_role
  expect select from orders to return all
}
```

## Running tests

```sh
# Run all policy tests in the schema file
scribase schema test schema.scribase

# Compile first to preview the generated SQL
scribase schema compile schema.scribase
```

Output:

```
running 5 policy tests...

  order owner can read their own order      PASS
  order owner cannot read another user's    PASS
  unauthenticated user cannot insert        PASS
  owner cannot update paid order            PASS
  service role can read all orders          PASS

5 passed, 0 failed
```

A failing test exits with code 1, suitable for use in CI.

## Mutation testing

A passing suite only proves something if it *can* fail. The standalone Aegis
harness adds mutation testing: it weakens each compiled policy on purpose (for
example, inverting an ownership check) against a real Postgres, and requires at
least one isolation test to catch every mutation. A mutation nobody catches is
reported as a coverage gap.

Mutation testing is not part of `scribase schema test`; run it with the Aegis
CLI, which ships alongside the Scribase source and uses its own `aegis.yaml`
schema and fixture format:

```sh
aegis compile aegis.yaml   # emit the SQL Aegis will test
aegis test                 # prove user A cannot read user B
aegis test --mutate        # prove each proof can fail
```

Fix the gap by adding a test:

```scribase
test "owner can update pending order" {
  as user { uid: "user-alice" }
  given orders { id: "ord-2", user_id: "user-alice", status: "pending", total: 50 }
  expect update orders set total = 60 where id = "ord-2" to succeed
}
```

## Known Postgres behaviors

Aegis is aware of several Postgres RLS behaviors that are easy to get wrong:

### RETURNING pulls SELECT policy

An `INSERT ... RETURNING *` checks both the `INSERT` and `SELECT` policies. If
the row you just inserted would not be visible to the current user via `SELECT`,
the `RETURNING` clause raises `insufficient_privilege`. Write separate policies
for INSERT and SELECT, or accept that `RETURNING` may be empty.

### `current_setting` returns empty string, not NULL

`current_setting('request.jwt.claim.sub', true)` returns `''` (empty string)
when the setting is unset — not `NULL`. A check like
`current_setting(...) IS NOT NULL` always passes.

Use `NULLIF`:

```sql
NULLIF(current_setting('request.jwt.claim.sub', true), '') IS NOT NULL
```

### FORCE RLS does not constrain superusers

A table owned by a superuser role bypasses `FORCE ROW LEVEL SECURITY`. Scribase
applies schemas as the `scribase_migrator` role (which has `BYPASSRLS`) but
tables are owned by application roles. Run `schema compile` to confirm ownership.

## Integrating with CI

```yaml
# .github/workflows/schema.yml
- name: Test RLS policies
  run: scribase schema test schema.scribase
```

A non-zero exit code fails the workflow. If you maintain an Aegis fixture as
well, add a second step that runs `aegis test --mutate`.