SupaForge README

SupaForge

Diff and sync your Supabase environments.

Supabase projects running as dev, staging and production drift apart, and nothing in Supabase tells you. A policy added in staging never reaches production; a bucket goes public in one place only; a cron job, webhook or grant exists on one side and not the other.

SupaForge finds every one of those differences across the whole project, not just the schema. It then makes the target match the source safely, and can prove the result before it touches anything.

CVE-2025-48757 found 170+ apps with exposed databases because RLS policies never reached production. SupaForge catches that on the first scan.

Built by Akal.

Why SupaForge

The whole project. It compares more than tables and columns:
- RLS policies and RLS coverage;
- storage buckets and their policies;
- auth config and Edge Functions;
- cron jobs, queues, webhooks and Realtime;
- Vault, extensions, roles and grants;
- reference data and migration history.
Fixes, not just reports. Fixes run in dependency order, in one transaction, and roll back cleanly if anything fails. Anything that would lose data or open up access waits for an explicit --allow-destructive.
Proof before change. --prove rehearses the migration on a throwaway copy of the target and applies nothing unless the result matches the source.
One project is enough. Snapshot a project's structure and configuration, restore it into an empty database (Supabase or plain PostgreSQL), or clone it locally with its data.
Hosted and self-hosted. It works with Supabase Cloud, self-hosted stacks, and local clones.
Built for pipelines and agents. --ci gives GitHub annotations and meaningful exit codes, --json output is machine-readable throughout, and a built-in MCP server lets AI agents scan and fix safely.

Quick start

Terminal

npm install -g @akal/supaforge

supaforge init              # create supaforge.config.json
supaforge diff              # what has drifted?
supaforge diff --detail     # with the SQL
supaforge diff --apply      # fix the target

Only one project?

bash

supaforge snapshot --env=prod --apply                       # record it
supaforge restore --env=local --from-snapshot=latest --apply
supaforge clone --env=prod --apply                          # local copy, data included

Everything that writes previews first. Add --apply to make it happen.

Also on Homebrew (brew install akalsoftware/tap/supaforge), as a GitHub Action, and as an MCP server for Cursor, VS Code and Claude, with one-click installs — see Install.

Full documentation →: the checks, commands, safety model, snapshots and restore, migrations, configuration, self-hosted Supabase, CI and MCP.

Under the hood

The schema and data checks are powered by DBDiff, installed automatically as a native binary with no PHP needed. Every release is tested by migrating a corpus of PostgreSQL shapes in both directions, and checking each result against an independent catalog oracle and against --prove.

Path	What
`packages/cli`	The `supaforge` CLI and library, published as `@akal/supaforge`
`packages/mcp`	A standalone build of the MCP server, not published. Use `supaforge mcp`

Development

bash

git clone https://github.com/akalsoftware/supaforge.git
cd supaforge/packages/cli
npm install
npm test && npm run lint
./bin/dev.js diff

The integration, database e2e, scenario and Supabase e2e suites are described in the package README. CI runs all of them on every pull request.

Releasing

Run the Trigger Release workflow (Actions → Trigger Release) with patch, minor, major or an exact version. It bumps the version, tags it, and publishes to npm.

node scripts/release.js patch does the same steps locally, as a dry run unless given --apply.