# scribase Supabase gives you a database and sign-in. Scribase is the whole backend for your app: Postgres, Auth, Storage, Realtime, Functions and migrations behind one flat price per project, with copy-on-write branching and an agent-native CLI/SDK/MCP surface built in from day one. This repo is the `npx scribase` CLI and the typed, fetch-based TypeScript client for the [Scribase](https://scribase.com) management `/v1` API, both shipped as the single `scribase` npm package. It talks to the same public `https://api.scribase.com` endpoint the dashboard and console use — nothing in this repo runs a database or a control plane itself. - **Zero runtime dependencies.** A thin, typed wrapper over `fetch`. - **Contract-first core.** `src/types.gen.ts` is emitted from `api/openapi.yaml` (orgs, memberships, projects, environments, operations, audit, imports, migrations, exports). Newer surfaces (backups, restores, usage, database, queues, functions, account, …) are typed by hand in `src/resources/*.ts` against the exact bodies `crates/control-api` renders; each type's doc comment names the server function it mirrors. - **Async-operation aware.** Every mutation returns an `Operation` to poll, and the client gives you `wait(...)` helpers so "accepted" becomes "done". - **Idempotency + retries built in.** Mutating calls attach an `Idempotency-Key` automatically; 429/503/network failures back off and retry. Requires Node >= 22.13 (built-in `fetch`, `crypto.randomUUID`) or any runtime with the Fetch and Web Crypto globals. ## `npx scribase init` The package also ships a `scribase` binary, made for coding agents (Claude Code, Codex, Cursor, Windsurf) and people alike: ```bash npx scribase init --json # not signed in: a 72-hour temporary project with a claim link # signed in (SCRIBASE_ACCESS_TOKEN or `scribase login`): your account npx scribase init --account # not signed in, but use an account (approve in the browser) npx scribase init --watch # also wait for the app's first request npx scribase sql "create table notes (id bigint generated always as identity primary key, body text)" # run SQL on this folder's project, in one transaction npx scribase doctor # check env vars, keys and the connection; one fix per problem ``` A new project's database is empty, so init's first next step creates a small `notes` table with `npx scribase sql` (row level security on, read-only for the public key) and the second queries it with `supabase.from('notes')`. `sql` holds back statements that remove data until you add `--confirm`. Init prints "Live in N s" with the measured time. The claim link carries `?ref=`, a random id stored in `~/.config/scribase/install-id` (`SCRIBASE_NO_REF=1` sends none). Claiming (sign up + card check) keeps the same URL and keys. It detects Next.js, Expo, Vite or plain Node, creates (or reuses) a project, writes the env file with that framework's variable names (`NEXT_PUBLIC_SUPABASE_URL`, `EXPO_PUBLIC_SUPABASE_URL`, `VITE_SUPABASE_URL`, `SUPABASE_URL`, and the anon key; the service-role key only where it cannot reach a client bundle), installs `@supabase/supabase-js`, writes a small client module and prints one JSON object (`ok`, `api_url`, `env_vars`, `client_file`, `claim_url`, `next_steps`, or `ok: false` with an error `code` and a `next` step). Run it again and it reuses the same project. When the folder is linked to Vercel (`.vercel/project.json` or `VERCEL_PROJECT_ID`), init also sets the URL and keys on that Vercel project for development, preview and production, using `VERCEL_TOKEN` or the signed-in `vercel` CLI, and reports `vercel: { status, targets }` (`updated`, `not_linked`, `no_credentials`, `failed`). It never fails init; `--no-vercel` turns it off. ## Install ```bash npm install scribase # or pnpm add scribase ``` Working on this repository directly? Clone it and build from source instead: ```bash git clone https://github.com/caelum0x/scribase-cli.git cd scribase-cli npm install npm run build npx ./dist/cli/index.js --help # or: npm link, then `scribase --help` npm install file:../path/to/scribase-cli # in your app, instead of the npm registry ``` ## Quick start ```ts import { ScribaseClient } from 'scribase'; const scribase = new ScribaseClient({ baseUrl: 'https://api.scribase.com', // your installation's management endpoint token: process.env.SCRIBASE_ACCESS_TOKEN ?? '', }); // Bootstrap an org (idempotent; caller becomes owner), then a project. await scribase.organizations.put('acme', { display_name: 'Acme, Inc.' }); await scribase.projects.put('acme', 'store', { region: 'us-east', postgres_major: 17 }); // Provision production. Mutations are asynchronous. 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, }); await scribase.operations.wait(operation.id, 'acme', { onUpdate: (op) => console.info(`provision: ${op.state}`), }); ``` ## Resources Every method maps to one real route in `crates/control-api/src/http.rs`. | Accessor | Methods → endpoints | |---|---| | `client.organizations` | `put`/`get` `/v1/organizations/{id}`, `update` (`PATCH`, rename), `list` `/v1/organizations`, `putMembership`/`listMemberships` `…/memberships`, `scheduleDeletion` (`DELETE`), `get`/`putNotificationSettings`, `listApiKeys`/`createApiKey`/`revokeApiKey` `…/api-keys`, `listPolicies`, `listMcpTools` | | `client.projects` | `put`/`get` `…/projects/{id}`, `list` `…/projects`, `listDomains` `…/domains` | | `client.environments` | `list`/`create` `/v1/environments`, `get`/`delete` `…/{env}`, `suspend`/`resume`/`renew`, `connection` (server-side only), `logs` | | `client.previews` | built on environments: `create`/`list`/`get`/`delete`/`renew` — TTL-swept, `sanitized` by default | | `client.backups` | `list`/`create` `…/environments/{env}/backups`, `get` `…/projects/{p}/backups/{id}?environment=`, `verify` `…/environments/{env}/backups/{id}/verify`, `restore` `…/backups/{id}/restore` | | `client.restores` | `start` — restore-shaped form of `backups.restore`; `list`/`get` `…/environments/{env}/restores[/{id}]`, `waitForCompletion` | | `client.export` | `create` `…/environments/{env}/exports`, `createForProject` `…/projects/{p}/export`, `list` `…/projects/{p}/exports`, `getManifest` `…/exports/{id}`, `downloadUrl`/`download` (signed `…/exports/{id}/download`) | | `client.migrations` | `run` `…/migrations` — plan → lint → apply | | `client.imports` | `create`/`dryRun` `/v1/imports`, `history`/`report` `…/imports` | | `client.usage` | `get` `…/environments/{env}/usage`, `capsNearingLimit`, `billing` `…/organizations/{org}/billing` | | `client.database` | `tables` `…/database/tables`, `query` `…/database/query` (read-only) | | `client.queues` | `list`, `peek`, `create`/`send`/`read`/`archive`/`delete`/`purge` | | `client.functions` | `list`, `deploy`, `invoke` | | `client.auth` | `listUsers`, `listProviders`, `listPolicies` | | `client.storage` / `client.realtime` / `client.metrics` / `client.insights` | read surfaces for the console | | `client.branches` | `list`/`register`/`diff`/`merge`/`linkPullRequest` | | `client.account` | `get`/`update` (`PATCH`) `/v1/account`, `security`, `revokeSession`/`removeFactor`, `enrollFactor`/`verifyFactor` (TOTP), `challenge` (MFA step-up), `listTokens`/`createToken`/`revokeToken` | | `client.operations` | `get` `/v1/operations/{id}`, `wait` | | `client.audit` | `list`, `paginate` over `…/audit-events` | ## The two money surfaces **Verified restore.** Backups become restorable only once the backup worker has verified them (`status: 'available'`); the control plane refuses anything else. A restore always lands in a *different* environment, and the finished record carries its own evidence: relation count, RLS relation count, and the SHA-256 of the evidence document. ```ts import { isRestorable, restoreEvidence } from 'scribase'; const production = { organizationId: 'acme', projectId: 'store', environmentId: 'production' }; const [latest] = (await scribase.backups.list(production)).filter(isRestorable); if (latest) { // Restore into a scratch preview, never over production, to prove the backup. const { restore } = await scribase.backups.restore(production, latest.backup_id, 'restore-check'); console.info(restore.id, restore.status); // 'pending' until the restore worker finishes const proof = restoreEvidence(restore); // non-null once status === 'restored' } ``` **Runnable export.** No lock-in: assemble a complete, runnable stack with a signed manifest. The call is synchronous and returns the manifest directly. ```ts const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' }; const { manifest, bundleRef } = await scribase.export.create(ref, { format: 'compose' }); // `manifest.artifacts[]` carries per-file sha256; `manifest.signature` signs the // manifest; `bundleRef` is where the control plane wrote the bundle. ``` ## Migrate an existing project The dry-run is the sales tool: it prints exactly what will move and what won't, before anything is written. Acceptance is binding — existing users log in afterward *without resetting passwords*. ```ts const source = { source: 'supabase' as const, sourceProjectRef: 'abcdefgh', sourceConnectionString: process.env.SOURCE_DB_URL ?? '', sourceServiceKey: process.env.SOURCE_SERVICE_KEY ?? '', // sent once, never logged destination: { organizationId: 'acme', projectId: 'store', environmentId: 'production' }, }; const plan = await scribase.imports.dryRun(source); // nothing is written const report = await scribase.imports.run(source); // starts it in the background, follows progress, returns the verified report // or: const job = await scribase.imports.createFrom(source); then scribase.imports.progress(job.import_id) ``` ## Apply migrations safely `plan → lint → apply`. A blocking lint finding (`missing_rls`, `public_grant`, `permissive_policy`, `no_with_check`, `security_definer`) refuses the migration before a single statement runs. ```ts const ref = { organizationId: 'acme', projectId: 'store', environmentId: 'production' }; const result = await scribase.migrations.run(ref, { migrations: [{ version: '20260921120000', name: 'add_notes', up: 'create table ...' }], apply: true, }); // result.plan, result.lintFindings, result.applied ``` ## Pagination ```ts for await (const event of scribase.audit.paginate('acme', { limit: 200 })) { console.info(event.sequence, event.action); } ``` ## Errors Every failure is a typed subclass of `ScribaseError`. API errors carry the parsed RFC 9457 `problem+json` body: ```ts import { ConflictError, QuotaExceededError } from 'scribase'; try { await scribase.environments.create(spec); } catch (error) { if (error instanceof QuotaExceededError) { // buy a capacity pack; retry after error.retryAfterSeconds } else if (error instanceof ConflictError) { console.error(error.problem.code, error.requestId); } } ``` ## Regenerating types `src/types.gen.ts` is generated; never edit it by hand. `scripts/generate.ts` reads the `api/openapi.yaml` contract from Scribase's main (private) repo, so regenerating it is a Scribase-team-only step — it is not needed to build, test or use this package, since `types.gen.ts` already ships checked in. ## License Apache-2.0. ## Ecosystem Part of the [Scribase](https://scribase.com) stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together. - [Scribase](https://scribase.com) — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required - [Toolgate](https://toolgate.scribase.com) — one key for agent tools, pay only for what you call - [Scribase Mail](https://mail.scribase.com) — Resend-compatible email API - More open-source projects from this account: [git.ereboslab.com/caelum0x](https://git.ereboslab.com/caelum0x)