Supabase is an open source Firebase alternative. We're building the features of Firebase using enterprise-grade open source tools.

This repository contains all the functionality for Supabase CLI.

• Running Supabase locally
• Managing database migrations
• Creating and deploying Supabase Functions
• Generating types directly from your database schema
• Making authenticated HTTP requests to Management API

Available via NPM as dev dependency. To install:

npm i supabase --save-dev

When installing with yarn 4, you need to disable experimental fetch with the following nodejs config.

NODE_OPTIONS=--no-experimental-fetch yarn add supabase

Note For Bun versions below v1.0.17, you must add supabase as a trusted dependency before running bun add -D supabase.

brew install supabase/tap/supabase

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

brew upgrade supabase

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

scoop update supabase

brew install supabase/tap/supabase

brew upgrade supabase

sudo apk add --allow-untrusted <...>.apk

sudo dpkg -i <...>.deb

sudo rpm -i <...>.rpm

sudo pacman -U <...>.pkg.tar.zst

go install github.com/supabase/cli@latest

ln -s "$(go env GOPATH)/bin/cli" /usr/bin/supabase

pkgx install supabase

supabase bootstrap

Or using npx:

npx supabase bootstrap

The bootstrap command will guide you through the process of setting up a Supabase project using one of the starter templates.

Command & config reference can be found here.

We follow semantic versioning for changes that directly impact CLI commands, flags, and configurations.

However, due to dependencies on other service images, we cannot guarantee that schema migrations, seed.sql, and generated types will always work for the same CLI major version. If you need such guarantees, we encourage you to pin a specific version of CLI in package.json.

To run from source:

# Go >= 1.22
go run . help

Supabase-CLI/
├── .github/ # GitHub Actions workflows, automation, release pipelines
├── api/ # OpenAPI specs and generated API clients
├── cmd/ # CLI commands (Cobra entrypoints)
├── docs/ # Additional CLI documentation
├── examples/ # Example projects, functions, templates
├── fsevents/ # File system event helpers (primarily macOS)
├── internal/ # Core business logic for the CLI
│ ├── api/ # Wrapped API client logic
│ ├── db/ # Migrations, schema tooling, dump/reset logic
│ ├── functions/ # Edge Functions tooling (build, deploy, logs)
│ ├── local/ # Local development orchestration (Docker stack)
│ ├── testing/ # Mocks and helpers for unit tests
│ └── ... # Additional internal packages
├── main.go # CLI entrypoint
├── go.mod # Go module definition
├── go.sum
├── package.json # JS tooling (type generation, scripts)
├── README.md
├── LICENSE
├── .gitignore
├── .golangci.yml # Linter configuration
└── .goreleaser.yml # Build & release configuration

Stable Release

• Published every two weeks from main

Beta Releases

• Published every merge to develop

Hotfix Releases

Create branch N.N.x from latest stable

Cherry-pick changes

Run Release (Beta) workflow

Test via:

npx supabase@N.N.x help

Mark release as latest stable

The CLI’s API client is generated from Supabase’s OpenAPI schema. Regenerate when updating API definitions.

This section helps you fix common issues when running or developing the Supabase CLI.

Problem: supabase start hangs, errors, or services don’t respond.

Common Causes

• Docker not Running
• Old containers/conflicting ports
• Missing environment files (.env)

Fix

# Make sure Docker is running
docker --version


# Stop any running Supabase stack
supabase stop


# Remove old containers if stuck
docker-compose down


# Start the local stack again
supabase start

Problem: CLI shows errors like migration already applied or schema mismatch.

Fix:

• Reset the local database (WARNING: deletes all data)

supabase db reset

• Apply migrations fresh

supabase db push

Problem: Commands fail after updating CLI or Go version.

Fix:

• Clear Go cache

go clean -cache

• Rebuild CLI binary

go build -o supabase .

• Check CLI works

./supabase help

Problem: supabase gen types typescript produces errors.

Fix:

• Ensure Node.js / npm / pnpm versions are correct

• Check database is running (supabase start)

npx supabase gen types typescript --local

Problem: Functions don’t deploy or logs show errors.

Fix:

• Make sure Docker is running

• Ensure folder structure under supabase/functions/ is correct

supabase functions build <function-name>
supabase functions deploy <function-name>

Every contribution — docs, tests, or code — makes Supabase better for everyone.

For detailed contribution workflow, branching, testing, and PR guidelines, see CONTRIBUTING.md.