12 KiB
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 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.tsis emitted fromapi/openapi.yaml(orgs, memberships, projects, environments, operations, audit, imports, migrations, exports). Newer surfaces (backups, restores, usage, database, queues, functions, account, …) are typed by hand insrc/resources/*.tsagainst the exact bodiescrates/control-apirenders; each type's doc comment names the server function it mirrors. - Async-operation aware. Every mutation returns an
Operationto poll, and the client gives youwait(...)helpers so "accepted" becomes "done". - Idempotency + retries built in. Mutating calls attach an
Idempotency-Keyautomatically; 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:
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
npm install scribase
# or
pnpm add scribase
Working on this repository directly? Clone it and build from source instead:
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
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.
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.
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.
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.
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
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:
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 stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together.
- Scribase — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required
- Toolgate — one key for agent tools, pay only for what you call
- Scribase Mail — Resend-compatible email API
- More open-source projects from this account: git.ereboslab.com/caelum0x