apps/docs/content/guides/local-development/cli/getting-started.mdx
The Supabase CLI enables you to run the entire Supabase stack locally, on your machine or in a CI environment. With two commands, you can set up and start a new local project:
supabase init to create a new local projectsupabase start to launch the Supabase servicesThere are two ways to install the CLI, and they change the command you type:
npm, pnpm, or yarn installs the CLI into a single project (there is no global supabase command with this method). Run it through your package runner instead, for example npx supabase <command>.supabase <command>.Either way, the CLI is project-scoped: most commands (including start) expect to run inside a directory that has been initialized with supabase init, which creates the supabase/ folder and config.toml. Run init first, then the other commands from the same directory.
The rest of this page writes examples as supabase <command>; translate them to npx supabase <command> if you installed the CLI as a project dependency.
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="platform"
<TabPanel id="npm" label="npm">
Install the CLI as a project dev dependency. This adds it to a single project rather than installing a global command:
npm install supabase --save-dev
# or: pnpm add -D supabase / yarn add -D supabase / bun add -D supabase
Pin the version in package.json so your whole team uses the same CLI version. Then run every command through your package runner:
npx supabase --help
# or: pnpm supabase / yarn supabase / bunx supabase
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.
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 via Homebrew and Linux packages.
brew install supabase/tap/supabase
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 <...>.apksudo dpkg -i <...>.debsudo rpm -i <...>.rpmPre-release CLI builds ship from the development branch (X.Y.Z-beta.N versions). Use the npm beta dist-tag, or install supabase-beta via Homebrew / Scoop (separate packages from stable).
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="platform"
<TabPanel id="npm" label="npm">
Install as a dev dependency:
npm install supabase@beta --save-dev
Or run without installing:
npx supabase@beta --help
brew install supabase/tap/supabase-beta
brew link --overwrite supabase-beta
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase-beta
brew install supabase/tap/supabase-beta
brew link --overwrite supabase-beta
Beta builds are attached to GitHub pre-releases. Download the .apk, .deb, or .rpm for your platform and install with the same commands as Linux packages above.
When a new version is released, you can update the CLI using the same channels.
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="platform"
<TabPanel id="npm" label="npm">
Update the CLI with npm:
npm update supabase --save-dev
Update to the latest beta release or switch a stable install to the beta channel with:
npm install supabase@beta --save-dev
brew upgrade supabase
Beta channel:
brew upgrade supabase-beta
scoop update supabase
Beta channel:
scoop update supabase-beta
brew upgrade supabase
Beta channel:
brew upgrade supabase-beta
sudo apk add --allow-untrusted <...>.apksudo dpkg -i <...>.debsudo rpm -i <...>.rpmIf 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.
<Admonition type="note" title="Backup and stop running containers">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
The most common thing you'll 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. Follow the official guide to install and configure Docker Desktop on your machine.
Alternately, you can use a different container tool that offers Docker compatible APIs.
With a container runtime running, go to the folder where you want to create your project and initialize it:
supabase init
This creates a new supabase folder. It's safe to commit this folder to version control.
Now, from the same folder, start the Supabase stack:
supabase start
If you installed the CLI as a project dependency (npm, pnpm, yarn, or bun), run these as npx supabase init and npx supabase start instead. See the note above.
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 stack, and a few additional images useful for local development (like a local SMTP server and a database diff tool).
Once all the Supabase services are running, you'll see output containing your local Supabase credentials. It should look like the below, with urls and keys that you use in your local project:
Started supabase local development setup.
╭──────────────────────────────────────╮
│ 🔧 Development Tools │
├─────────┬────────────────────────────┤
│ Studio │ http://127.0.0.1:54323 │
│ Mailpit │ http://127.0.0.1:54324 │
│ MCP │ http://127.0.0.1:54321/mcp │
╰─────────┴────────────────────────────╯
╭──────────────────────────────────────────────────────╮
│ 🌐 APIs │
├────────────────┬─────────────────────────────────────┤
│ Project URL │ http://127.0.0.1:54321 │
│ REST │ http://127.0.0.1:54321/rest/v1 │
│ GraphQL │ http://127.0.0.1:54321/graphql/v1 │
│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
╰────────────────┴─────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────╮
│ ⛁ Database │
├─────┬─────────────────────────────────────────────────────────┤
│ URL │ postgresql://postgres:[email protected]:54322/postgres │
╰─────┴─────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────╮
│ 🔑 Authentication Keys │
├─────────────┬────────────────────────────────────────────────┤
│ Publishable │ sb_publishable_... │
│ Secret │ sb_secret_... │
╰─────────────┴────────────────────────────────────────────────╯
<Tabs scrollable size="small" type="underlined" defaultActiveId="studio" queryGroup="access-method"
<TabPanel id="studio" label="Studio">
# Default URL:
http://localhost:54323
The local development environment includes Supabase Studio, a graphical interface for working with your database.
</TabPanel> <TabPanel id="postgres" label="Postgres"># 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: sb_publishable_..."
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)
sb_publishable_... is the publishable key output 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.
</Admonition>All logs are stored in the local database under the _analytics schema.
When you are finished working on your Supabase project, you can stop the stack (without resetting your local database):
supabase stop
The Supabase CLI collects telemetry data about general usage. Participating in this program is optional, and you can opt out at any time.
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.