2026-11-12 18:10:58 +03:00
# 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=<install id>` , 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.
2026-11-16 14:35:20 +00:00
## 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 )