Prerequisites

• Node.js installed (v18 or later recommended)
• A Supabase account
• An existing Supabase project (or you can create one during setup)

Installation

You can install the Supabase CLI using several package managers.

macOS (Homebrew):

brew install supabase/tap/supabase

npm (cross-platform):

npm install -g supabase

Windows (Scoop):

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

Verify the installation:

supabase --version

Logging In

To authenticate the CLI with your Supabase account, run:

supabase login

This opens a browser window where you can generate an access token. Paste it back into the terminal when prompted. Your token is saved locally so you only need to do this once.

To confirm you're logged in:

supabase projects list

This returns a list of all projects under your account, along with their project refs — which you'll need in the next step.

Linking to a Project

Once logged in, navigate to your local project directory and run:

supabase link --project-ref <your-project-ref>

Finding your project ref:

Your project ref is the unique ID in your Supabase dashboard URL:

https://supabase.com/dashboard/project/<your-project-ref>

You can also find it under Project Settings → General.

Example:

supabase link --project-ref abcdefghijklmnopqrst

You'll be prompted for your database password. You can also pass it directly:

supabase link --project-ref abcdefghijklmnopqrst --password your-db-password

Once linked, the project ref is saved in .supabase/config.toml inside your project directory.

What You Can Do After Linking

With your project linked, you can now run commands that interact with your remote Supabase project:

Initializing a Local Project

If you haven't already, you can initialize Supabase in your local project directory:

supabase init

This creates a supabase/ folder with a config.toml and a migrations/ directory. This is where your local schema migrations and seed files live.

Common Workflow

Here's a typical day-to-day workflow using the CLI:

# 1. Log in (first time only)
supabase login

# 2. Initialize local project (first time only)
supabase init

# 3. Link to your remote project
supabase link --project-ref <your-project-ref>

# 4. Pull the current remote schema
supabase db pull

# 5. Make changes locally, then push
supabase db push

Logging Out

To remove your stored credentials:

supabase logout

Further Reading

• Supabase CLI Reference
• Local Development with Supabase
• Managing Migrations