supabase init and start commands for local development
To run the entire Supabase stack locally on your machine, execute `supabase init` followed by `supabase start`.
cli
99 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Supabase CLI GitHub repository
The Supabase CLI source code and documentation are available at https://github.com/supabase/cli. It provides tools to manage your Supabase projects from your local machine.
Supabase CLI capabilities
The Supabase CLI provides tools to develop your project locally, deploy to the Supabase Platform, handle database migrations, and generate types directly from your database schema.
GitHub Action for Supabase CLI
A GitHub Action is available at https://github.com/supabase/setup-cli for interacting with Supabase projects using the CLI within GitHub workflows.
Supabase CLI init command
Run `supabase init` to initialize your local ./supabase directory if it does not already exist.
Login to Supabase CLI
Use `supabase login` to authenticate with the Supabase CLI using an auto-generated Personal Access Token.
Link CLI to remote project
Use `supabase link` to connect the CLI to your remote Supabase project. The command prompts you to select the project from a list.
List migration status
Use `supabase migration list` to show which migrations are applied locally, which are applied on the remote database, and where they diverge.
Supabase CLI
Use the Supabase CLI to develop your project locally and deploy to the Supabase Platform. This feature is generally available and fully works with self-hosted deployments.
Install Supabase CLI via Homebrew
To install Supabase CLI globally using Homebrew, run: brew install supabase/tap/supabase. This gives you a global supabase command.
Supabase CLI capabilities
The Supabase CLI enables developers to run Supabase services locally and manage hosted projects directly from the terminal. It provides commands for setting up and managing local development environments, generating TypeScript types for your database schema, handling database migrations, managing environment variables and secrets, and deploying your project to the Supabase platform.
Install Supabase CLI via yarn
To install Supabase CLI as a project dependency using yarn, run: NODE_OPTIONS=--no-experimental-fetch yarn add supabase --dev. This installs the CLI into your project as a dev dependency, requiring you to run it through yarn supabase.
Start local Supabase stack with Homebrew
To start the local Supabase stack when using Homebrew-installed CLI, run: supabase start.
Local stack not hardened for production
The local stack brought up by `supabase start` is for development only. It is not hardened for production use and must never be exposed to external traffic. It has no TLS, no rate limiting, and default credentials. Use it to develop and test, then deploy to the Supabase Platform or a proper self-hosted setup for anything beyond development.
Seed data example with test user and application data
Example of seed data in `supabase/seed.sql`: ```sql -- Create a test user (Supabase Auth) -- Note: this is a placeholder row so seeded data has a user_id to reference. -- It has no password, so it can't be used to sign in. To create a -- login-capable user, use the Auth admin API or the local Studio. insert into auth.users (id, email, raw_user_meta_data) values ('d0e3c8f0-1234-5678-9abc-def012345678', 'test@example.com', '{}'); -- Seed application data insert into public.todos (title, user_id) values ('Buy groceries', 'd0e3c8f0-1234-5678-9abc-def012345678'), ('Write documentation', 'd0e3c8f0-1234-5678-9abc-def012345678'); ```
Extension statements in generated migrations
`CREATE EXTENSION IF NOT EXISTS ...` may appear in generated migrations. Keep it if the extension is required by your migration. Remove it if the extension is already created by a previous migration or is part of the default Supabase setup.
REVOKE/GRANT patterns in generated migrations
Generated migrations may produce `REVOKE ALL ON TABLE public.todos FROM anon;` followed by `GRANT ALL ON TABLE public.todos TO anon;`. This is the diff tool being overly cautious. If you haven't changed permissions, these lines can be safely removed.
supabase start runs local development stack
Running `supabase start` starts the local stack. On first run, Docker images are pulled, which takes several minutes. Subsequent starts are fast. Once running, the CLI outputs local service URLs and credentials including the Studio URL for a local instance of the Dashboard.
supabase init creates config.toml
Running `supabase init` creates a `./supabase/config.toml` file and establishes a `./supabase` directory structure in your project root alongside application code.
supabase login generates and stores access token
Running `supabase login` opens a browser to generate an access token that is stored locally and used for all subsequent CLI commands interacting with the platform.
supabase link connects to remote project
Running `supabase link --project-ref <project-id>` tells the CLI which remote project to connect to for db pull, db push, and other remote operations. The project ID is found in the Supabase Dashboard URL at `https://supabase.com/dashboard/project/<project-id>`. When linking, you will be prompted for the database password that was set when the project was created.
supabase db pull creates baseline migration
Running `supabase db pull` connects to the remote database, dumps the entire schema, and saves it as a migration file at `supabase/migrations/<timestamp>_remote_schema.sql`. This initial migration represents the current state of the database, and all future changes build on top of it. The command also records the migration as already applied in the remote migration history (the `supabase_migrations.schema_migrations` table) so a later `db push` won't try to reapply it.
supabase db pull with schema filter
To pull Auth or Storage schemas separately, use `supabase db pull --schema auth -f pull-auth-schema` or `supabase db pull --schema storage -f pull-storage-schema`. These schemas are managed by Supabase and typically don't need to be pulled unless custom modifications have been made.
supabase db dump exports data or schema
Running `supabase db dump --data-only --linked > supabase/seed.sql` exports only data from the remote database via pg_dump. Without the `--data-only` flag, it exports the schema. The `--linked` flag targets the remote project.
supabase db reset destroys and recreates local database
Running `supabase db reset` destroys the local database and recreates it from scratch by applying all migrations in order, then running seed.sql. This command defaults to `--local` targeting the local database.
supabase db diff generates migration from schema changes
Running `supabase db diff -f <name>` generates a migration file by comparing the current database state (or declarative schema files) against a shadow database. For projects with declarative schema files in `supabase/schemas/`, `db diff` compares those files against existing migrations, not the live database. For projects without declarative files, `db diff` compares the live local database against migrations.
supabase migration new creates empty migration file
Running `supabase migration new <name>` creates an empty migration file at `supabase/migrations/<timestamp>_<name>.sql`. You write SQL in the file and then apply it with `supabase db reset`.
supabase db push applies pending migrations to remote
Running `supabase db push` applies only migrations that haven't been applied to the remote yet. It tracks applied migrations via the `supabase_migrations.schema_migrations` table created automatically on the remote database. Use `supabase db push --dry-run` to preview what will be applied.
supabase db push with seed data
Running `supabase db push --include-seed` applies pending migrations to the remote and also seeds a fresh remote instance with data from seed.sql. Never use `--include-seed` on a production database.
supabase db reset --linked destroys remote database
Running `supabase db reset --linked` destroys the remote database linked via `supabase link`, then replays every local migration in order to rebuild it. This is destructive and erases all data in the linked remote database. Only run it against throwaway dev or staging projects, and double-check which project you're linked to with `supabase projects list` before running. Never use it on production. Add `--include-seed` to reload seed data as well.
supabase gen types generates TypeScript types from schema
Running `supabase gen types --lang typescript --local > database.types.ts` generates TypeScript types from the local database schema. Use `--linked` instead of `--local` to generate from the remote project. Pass `--lang go`, `--lang swift`, or `--lang python` for other languages. TypeScript is the default language.
supabase migration list compares local vs remote
Running `supabase migration list` compares local migrations against the remote migration history to show which migrations are applied, pending, or out of sync.
supabase/config.toml is safe to commit
The `config.toml` file contains local stack configuration (ports, auth settings, etc.) and is safe to commit because it contains no secrets by default. If you add sensitive values such as OAuth credentials or API keys, use the `env()` function to reference environment variables instead of hardcoding them.
supabase/migrations/ and supabase/seed.sql should be committed
Timestamped SQL migration files in `supabase/migrations/` and `supabase/seed.sql` (dev/test data applied after migrations) should be committed to version control. These are applied in order on `supabase start` and `supabase db reset`.
supabase/.temp/ and supabase/.branches/ should not be committed
The `.temp/` and `.branches/` directories inside the supabase directory contain CLI internal state and should not be committed to version control.
supabase/schemas/ directory for declarative schemas
The `supabase/schemas/` directory contains declarative schema files and should be committed. Declarative schemas are recommended for new projects as an alternative to imperative migrations.
db diff and db reset default targets differ
Many database commands accept `--local` and `--linked` flags to choose what they act on. The defaults are not the same across commands: `db diff` and `db reset` default to `--local` (local database), while `db pull`, `db push`, and `db dump` default to `--linked` (remote project). When in doubt, pass the flag explicitly.
Review db pull generated migrations before committing
When `supabase db pull` generates a migration, review the generated file before committing it because it diffs the remote database against the CLI's default local stack, so it can include unexpected statements. A common example is `DROP EXTENSION pg_net;` emitted when the remote project has an extension disabled that the local stack enables by default. These statements apply silently on `db reset` and change your local schema.
Review and clean seed data dumps before committing
When dumping existing data from remote with `supabase db dump --data-only --linked > supabase/seed.sql`, review and clean up the dump before committing. Remove production user data, secrets, personal information, and anything sensitive. Keep only representative test data that a developer needs to work with the project.
Declarative schema workflow
With declarative schemas: (1) edit schema files in `supabase/schemas/`, (2) generate a migration with `supabase db diff -f <name>`, (3) review the generated migration file, (4) verify the full chain with `supabase db reset`, (5) commit the schema file and the migration together.
db diff ignores Studio UI changes in declarative mode
When using declarative schemas, `db diff` compares your `supabase/schemas/` files against your existing migrations; it does not read the live local database. Changes made directly in Studio or via SQL are ignored, so `db diff` reports 'No schema changes found' and silently drops them. Always edit the schema files, then diff.
Imperative migration workflow with direct SQL
To write SQL migrations directly: (1) run `supabase migration new <name>` to create an empty migration file, (2) write SQL in the generated file at `supabase/migrations/<timestamp>_<name>.sql`, (3) verify with `supabase db reset`, (4) commit the migration.
Imperative migration workflow with Studio UI
If you made changes through the local Studio UI and your project has no declarative files in `supabase/schemas/`, run `supabase db diff -f <name>` to capture your UI changes as a migration file. This works only when there are no declarative schema files, because `db diff` then compares the live local database against your migrations.
Sync team changes with git pull and db reset
When someone else on your team pushes new migrations, run `git pull` followed by `supabase db reset`. The `db reset` command replays all migrations from scratch, so you'll always match the current state of the repository.
Detect schema drift with db pull
If someone modified the remote database directly via Dashboard or SQL editor (outside of migrations), run `supabase db pull` to capture those changes as a new migration file. Then run `supabase db reset` locally to verify everything still works.
Fix migration errors in db reset
If `db reset` fails with a migration error, the output shows which migration file failed and the SQL error. Fix the migration file and then run `db reset` again.
Use migration repair for out-of-sync remote history
If `db push` says migrations are already applied but they appear out of sync, run `supabase migration list` to compare local vs. remote state. If they're out of sync, use `supabase migration repair` to correct the remote migration history.
Docker resource requirement for supabase start
When running `supabase start`, Docker must be running and have at least 7 GB of RAM allocated. If containers fail health checks, try stopping and starting again with `supabase stop` and `supabase start`. If problems persist, run `supabase stop --no-backup` for a clean restart (this removes local database data).
CLI invocation depends on installation method
How you invoke the CLI depends on how you installed it: if installed globally with Homebrew or Scoop, run `supabase <command>`; if added as a project dependency with npm, pnpm, yarn, or bun, run it through your package runner, for example `npx supabase <command>` (or `pnpm supabase`, `yarn supabase`, `bunx supabase`).
supabase bootstrap creates starter project
Running `supabase bootstrap` scaffolds a starter application (Next.js, Flutter, and more) with schema, migrations, and config already wired up. It is an alternative entry point to `supabase init` when starting a new project from scratch.
supabase stop preserves data until db reset
Running `supabase stop` stops the local stack. Data persists until `supabase db reset` is run.
Seed data placeholder user for Auth
When seeding test data that references auth.users, insert a placeholder row into auth.users with a UUID and email. This allows seeded application data to reference the user_id. The placeholder row can have no password so it cannot be used to sign in; to create a login-capable user, use the Auth admin API or the local Studio.
GRANT statements in generated migrations
Generated migrations may include GRANT statements like `GRANT MAINTAIN, REFERENCES, TRIGGER, TRUNCATE ON public.todos TO anon;` for the anon, authenticated, and service_role roles. These appear because the diff tool treats permissions as part of the schema state. For tables in the public schema, these grants are applied by default and the lines are redundant. They're harmless, but can be removed for clean migrations if your team is consistent about it.
Declarative schema example with RLS
Example of a declarative schema file in `supabase/schemas/schema.sql`: ```sql create table public.todos ( id bigint generated by default as identity primary key, created_at timestamptz default now() not null, title text not null, is_complete boolean default false not null, user_id uuid references auth.users (id) default auth.uid() not null ); alter table public.todos enable row level security; create policy "Users can read their own todos" on public.todos for select using (auth.uid() = user_id); create policy "Users can create their own todos" on public.todos for insert with check (auth.uid() = user_id); ``` After creating the schema file, generate a migration with `supabase db diff -f initial-schema`.
db diff engine and caveats
The diff is generated by pg-delta, the default schema diff engine. The older migra engine is still available: set `enabled = false` under `[experimental.pgdelta]` in `config.toml`, or pass `--use-migra`. No diff engine captures everything. DML (INSERT, UPDATE, DELETE) is not tracked, so data changes must be added to migrations manually. Some entities like RLS policy renames and certain view properties don't diff cleanly. Treat `db diff` output as a draft, not a final migration.
Local Supabase API Gateway default URL
The local API Gateway is available at http://localhost:54321. Services are accessible at: http://localhost:54321/rest/v1/ (REST/PostgREST), http://localhost:54321/realtime/v1/ (Realtime), http://localhost:54321/storage/v1/ (Storage), and http://localhost:54321/auth/v1/ (Auth/GoTrue). When accessing without client libraries, pass the publishable key as an Authorization header: `curl 'http://localhost:54321/rest/v1/' -H "apikey: sb_publishable_..."`
Install Supabase CLI via Scoop
On Windows, install the CLI with Scoop using: `scoop bucket add supabase https://github.com/supabase/scoop-bucket.git` followed by `scoop install supabase`
Install Supabase CLI on Linux via packages
Linux packages are provided in the Supabase CLI releases. Download the `.apk`, `.deb`, or `.rpm` file depending on your package manager and install with one of: `sudo apk add --allow-untrusted <...>.apk`, `sudo dpkg -i <...>.deb`, or `sudo rpm -i <...>.rpm`
Beta channel CLI installation
Pre-release CLI builds ship from the development branch with versions like `X.Y.Z-beta.N`. Use the npm `beta` dist-tag with `npm install supabase@beta --save-dev` or `npx supabase@beta --help`. On Homebrew, install `supabase-beta` with `brew install supabase/tap/supabase-beta` and `brew link --overwrite supabase-beta`. On Scoop, use `scoop install supabase-beta`. Beta Linux packages are attached to GitHub pre-releases.
Update Supabase CLI via npm
Update the CLI with `npm update supabase --save-dev`. To update to the latest beta release or switch from stable to beta, use `npm install supabase@beta --save-dev`.