Supabase CLI

The Supabase CLI enables you to run the entire Supabase stack locally, on your machine or in a CI environment. With just two commands, you can set up and start a new local project:

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

Installing the Supabase CLI

<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="platform"

Install the CLI with Homebrew:

brew install supabase/tap/supabase

Install the CLI with Scoop:

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

The CLI is available through Homebrew and Linux packages.

Homebrew

brew install supabase/tap/supabase

Linux packages

Linux packages are provided in Releases. To install, download the .apk/.deb/.rpm file depending on your package manager and run one of the following:

• sudo apk add --allow-untrusted <...>.apk
• sudo dpkg -i <...>.deb
• sudo rpm -i <...>.rpm

Run the CLI by prefixing each command with npx or bunx:

npx supabase --help

The Supabase CLI requires Node.js 20 or later when run via npx or npm. Older Node.js versions, such as 16, are not supported and fail to start the CLI.

Installing the Supabase CLI globally using npm install -g supabase is not supported.

For global usage, install the CLI via Homebrew, Scoop, or the standalone binary.

Alternatively, you can run the CLI using npx supabase or install it locally as a dev dependency.

You can also install the CLI as dev dependency via npm:

npm install supabase --save-dev

Global installation using npm install -g supabase is not supported. For global CLI usage, install via Homebrew, Scoop, or the standalone binary.

Updating the Supabase CLI

When a new version is released, you can update the CLI using the same methods.

<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="platform"

brew upgrade supabase

scoop update supabase

Homebrew

brew upgrade supabase

Linux package manager

1. Download the latest package from the Supabase CLI releases page
2. Install the package using the same commands as the initial installation:
   • sudo apk add --allow-untrusted <...>.apk
   • sudo dpkg -i <...>.deb
   • sudo rpm -i <...>.rpm

If you have installed the CLI as dev dependency via npm, you can update it with:

npm update supabase --save-dev

If you have any Supabase containers running locally, stop them and delete their data volumes before proceeding with the upgrade. This ensures that Supabase managed services can apply new migrations on a clean state of the local database.

Remember to save any local schema and data changes before stopping because the --no-backup flag will delete them.

supabase db diff -f my_schema
supabase db dump --local --data-only > supabase/seed.sql
supabase stop --no-backup

<$Show if="!docs:hide_cli_profiles">

<$Partial path="cli_profiles.mdx" />

</$Show>

Running Supabase locally

The Supabase CLI uses Docker containers to manage the local development stack. Follow the official guide to install and configure Docker Desktop:

<Tabs scrollable size="small" type="underlined" defaultActiveId="macos" queryGroup="platform"

<Image alt="Docker settings on Mac: Select Integrated, Virtualization Framework, and osxfs" src={{ dark: '/docs/img/guides/cli/docker-mac.png', light: '/docs/img/guides/cli/docker-mac-light.png', }}

width={2880} height={1800} />

<Image alt="Docker settings on Windows: Select Integrated, Expose Daemon, WSL2, and Add to /etc/hosts file." src={{ dark: '/docs/img/guides/cli/docker-win.png', light: '/docs/img/guides/cli/docker-win-light.png', }}

width={2560} height={1520} />

Alternately, you can use a different container tool that offers Docker compatible APIs.

• Rancher Desktop (macOS, Windows, Linux)
• Podman (macOS, Windows, Linux)
• OrbStack (macOS)
• colima (macOS)

Inside the folder where you want to create your project, run:

supabase init

This will create a new supabase folder. It's safe to commit this folder to your version control system.

Now, to start the Supabase stack, run:

supabase start

This takes time on your first run because the CLI needs to download the Docker images to your local machine. The CLI includes the entire Supabase toolset, and a few additional images that are useful for local development (like a local SMTP server and a database diff tool).

Access your project's services

Once all of the Supabase services are running, you'll see output containing your local Supabase credentials. It should look like this, with urls and keys that you'll use in your local project:

Started supabase local development setup.

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
     Mailpit URL: http://localhost:54324
        anon key: eyJh......
service_role key: eyJh......

<Tabs scrollable size="small" type="underlined" defaultActiveId="studio" queryGroup="access-method"

# Default URL:
http://localhost:54323

The local development environment includes Supabase Studio, a graphical interface for working with your database.

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

The local Postgres instance can be accessed through psql or any other Postgres client, such as pgAdmin. For example:

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

To access the database from an edge function in your local Supabase setup, replace localhost with host.docker.internal.

# Default URL:
http://localhost:54321

If you are accessing these services without the client libraries, you may need to pass the client keys as an Authorization header. Learn more about JWT headers.

curl 'http://localhost:54321/rest/v1/' \
    -H "apikey: <anon key>" \
    -H "Authorization: Bearer <anon key>"

http://localhost:54321/rest/v1/           # REST (PostgREST)
http://localhost:54321/realtime/v1/       # Realtime
http://localhost:54321/storage/v1/        # Storage
http://localhost:54321/auth/v1/           # Auth (GoTrue)

<anon key> is provided when you run the command supabase start.

Local logs rely on the Supabase Analytics Server which accesses the docker logging driver by either volume mounting /var/run/docker.sock domain socket on Linux and macOS, or exposing tcp://localhost:2375 daemon socket on Windows. These settings must be configured manually after installing the Supabase CLI.

For advanced logs analysis using the Logs Explorer, it is advised to use the BigQuery backend instead of the default Postgres backend. Read about the steps here.

All logs will be stored in the local database under the _analytics schema.

Stopping local services

When you are finished working on your Supabase project, you can stop the stack (without resetting your local database):

supabase stop

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

You can disable telemetry by running:

supabase telemetry disable

You can check the current status and re-enable with:

supabase telemetry status
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