Supabase CLI

The Supabase CLI runs the entire Supabase stack on your own machine or in a CI environment, so you can build and test locally, then connect your project to a hosted one when you're ready to deploy.

• Quickstart is the two-command version, if you already have the CLI and a container runtime.
• Set up a local project installs the CLI and brings the stack up on your machine. Start here if you haven't run it before.
• Connect to a hosted project links your local directory to a project on the Supabase Platform.
• Change your CLI version updates the CLI and switches between stable and pre-release builds.
• Telemetry covers what the CLI collects and how to opt out.

Quickstart

With two commands, you can set up and start a new local project:

1. Run supabase init to create a new local project.
2. Run supabase start to launch the Supabase services.

Set up a local project

Install the CLI, bring the Supabase stack up on your machine, and stop it when you're done.

Install the Supabase CLI

1
brew install supabase/tap/supabase

1
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
2
scoop install supabase

1
brew install supabase/tap/supabase

Run a local Supabase project

The most common thing you do with the CLI is run the full Supabase stack (Postgres, Auth, Storage, and the rest) on your own machine. That stack runs in Docker containers, so you need a container runtime installed first. On Windows and Linux, follow the official guide to install and configure Docker Desktop. In a coding agent sandbox or on a CI runner with no container engine, the experimental native runtime runs each service as a process instead. It supports Linux and macOS on Apple silicon. For platform requirements and setup, see Docker and native runtimes.

On macOS, we recommend OrbStack instead of Docker Desktop. It's a drop-in replacement that handles extended file attributes (xattrs) on mounted volumes and container networking more reliably than Docker Desktop. It also starts faster and uses less CPU, memory, and disk, which makes a noticeable difference when running the full Supabase stack.

Alternatively, you can use a different container tool that offers Docker-compatible APIs:

To bring the stack up:

1. Start your container runtime.

2. Open a terminal in the directory where you want to create your project.

3. Initialize the project:

   1
   supabase init

   The command creates a supabase directory, which is safe to commit to version control. init creates local files only: it doesn't sign you in or connect the directory to a project on the Supabase Platform. To connect one, see Connect to a hosted project.

4. Start the Supabase services from the same directory:

   1
   supabase start

The first run takes time while the CLI downloads the Docker images. It pulls the entire Supabase stack, plus a few extra images useful for local development, such as a local SMTP server and a database diff tool.

Access your project's services

After all the Supabase services are running, the CLI prints your local credentials. The output looks like this, with the URLs and keys you use in your local project:

1
Started supabase local development setup.
2
3
╭──────────────────────────────────────╮
4
│ 🔧 Development Tools                 │
5
├─────────┬────────────────────────────┤
6
│ Studio  │ http://127.0.0.1:54323     │
7
│ Mailpit │ http://127.0.0.1:54324     │
8
│ MCP     │ http://127.0.0.1:54321/mcp │
9
╰─────────┴────────────────────────────╯
10
11
╭──────────────────────────────────────────────────────╮
12
│ 🌐 APIs                                              │
13
├────────────────┬─────────────────────────────────────┤
14
│ Project URL    │ http://127.0.0.1:54321              │
15
│ REST           │ http://127.0.0.1:54321/rest/v1      │
16
│ GraphQL        │ http://127.0.0.1:54321/graphql/v1   │
17
│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
18
╰────────────────┴─────────────────────────────────────╯
19
20
╭───────────────────────────────────────────────────────────────╮
21
│ ⛁ Database                                                    │
22
├─────┬─────────────────────────────────────────────────────────┤
23
│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
24
╰─────┴─────────────────────────────────────────────────────────╯
25
26
╭──────────────────────────────────────────────────────────────╮
27
│ 🔑 Authentication Keys                                       │
28
├─────────────┬────────────────────────────────────────────────┤
29
│ Publishable │ sb_publishable_...                             │
30
│ Secret      │ sb_secret_...                                  │
31
╰─────────────┴────────────────────────────────────────────────╯

1
# Default URL:
2
http://localhost:54323

1
# Default URL:
2
postgresql://postgres:postgres@localhost:54322/postgres

1
psql 'postgresql://postgres:postgres@localhost:54322/postgres'

1
# Default URL:
2
http://localhost:54321

1
curl 'http://localhost:54321/rest/v1/' \
2
    -H "apikey: sb_publishable_..."
3
4
http://localhost:54321/rest/v1/           # REST (PostgREST)
5
http://localhost:54321/realtime/v1/       # Realtime
6
http://localhost:54321/storage/v1/        # Storage
7
http://localhost:54321/auth/v1/           # Auth (GoTrue)

Stop local services

When you finish working, stop the stack. Stopping doesn't reset your local database:

1
supabase stop

With the default ports, supabase start runs one local project per machine, because every project's config.toml uses the same ports. To run several local projects or git worktrees at the same time, see Running multiple local projects.

Connect to a hosted project

The stack you started in Run a local Supabase project runs only on your machine. Nothing reaches a hosted project until you sign in to the CLI and link your local directory to one.

For the steps, see Pushing to a remote project. To run deployments from CI, see Configure GitHub Actions.

Change your CLI version

These sections cover the CLI itself rather than your local project.

Use the beta channel

Pre-release CLI builds ship from the development branch and are versioned X.Y.Z-beta.N. Use the npm beta dist-tag, or install supabase-beta with Homebrew or Scoop. supabase-beta is a separate package from supabase.

1
npm install supabase@beta --save-dev

1
npx supabase@beta --help

1
brew install supabase/tap/supabase-beta
2
brew link --overwrite supabase-beta

1
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
2
scoop install supabase-beta

1
brew install supabase/tap/supabase-beta
2
brew link --overwrite supabase-beta

Update the Supabase CLI

Update the CLI with the same package manager you installed it with. See the CLI releases page for available versions.

1
npm update supabase --save-dev

1
npm install supabase@beta --save-dev

1
brew upgrade supabase

1
brew upgrade supabase-beta

1
scoop update supabase

1
scoop update supabase-beta

1
brew upgrade supabase

1
brew upgrade supabase-beta

If you have any Supabase containers running locally, stop them and delete their data volumes before upgrading. Deleting the volumes lets Supabase managed services apply new migrations on a clean local database.

1. Save local schema changes as a migration:

   1
   supabase db diff -f my_schema

2. Dump local data to your seed file:

   1
   supabase db dump --data-only > supabase/seed.sql

3. Stop the containers and delete their data volumes:

   1
   supabase stop --no-backup

Telemetry

The Supabase CLI collects telemetry data about general usage. Participating in this program is optional, and you can opt out at any time.

How to opt out

1. Disable telemetry:

   1
   supabase telemetry disable

2. Confirm the current setting:

   1
   supabase telemetry status

To enable telemetry again, run supabase telemetry enable.

You can also opt out using the SUPABASE_TELEMETRY_DISABLED=1 environment variable. The broader DO_NOT_TRACK=1 convention is also respected.

Learn more

• CLI configuration
• CLI reference