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.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:

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
Description
npx scribase CLI + TypeScript SDK for Scribase (Supabase/Neon alternative): one flat price per project, agent-native, copy-on-write Postgres branching.
https://scribase.com Readme Apache-2.0 259 KiB
Languages
TypeScript 93.8%
JavaScript 6.2%