Install the Supabase CLI with brew install supabase/tap/supabase (macOS) or npm install supabase --save-dev (any OS). Run supabase init to create the project structure, supabase start to launch local Postgres, Auth, Storage, and Studio, and supabase link to connect to your remote project. The CLI is essential for migrations, Edge Functions, type generation, and local development — it gives you a full Supabase stack on your machine.
Installing and Configuring the Supabase CLI
The Supabase CLI is the command-line tool for local development, database migrations, Edge Functions, and type generation. It runs a complete Supabase stack locally using Docker — including PostgreSQL, Auth (GoTrue), Storage, Realtime, and Studio. This tutorial walks you through installation, project initialization, linking to a remote project, and the essential commands you will use daily.
Prerequisites
- Docker Desktop installed and running (required for supabase start)
- A Supabase account at app.supabase.com
- A terminal (macOS Terminal, Linux shell, or WSL on Windows)
- Node.js 18+ (if installing via npm)
Step-by-step guide
Install the Supabase CLI
Install the Supabase CLI
The CLI can be installed via Homebrew on macOS, npm for any platform, or as a standalone binary. The Homebrew method is recommended for macOS because it auto-updates and handles PATH configuration. The npm method works everywhere and is ideal for projects where you want the CLI version locked in package.json. After installation, verify it works by running supabase --version.
1# macOS (recommended)2brew install supabase/tap/supabase34# Any OS via npm (add to your project)5npm install supabase --save-dev67# Run via npx if installed via npm8npx supabase --version910# Linux (direct download)11brew install supabase/tap/supabase12# or use npm method above1314# Verify installation15supabase --versionExpected result: The CLI prints its version number, confirming successful installation.
Initialize a Supabase project
Initialize a Supabase project
Navigate to your project directory and run supabase init. This creates a supabase/ folder containing config.toml (project configuration), a migrations/ directory for SQL migration files, a functions/ directory for Edge Functions, and a seed.sql file for seeding your local database. The config.toml file controls local settings like the Studio port, auth configuration, and database extensions. You only need to run init once per project.
1# Navigate to your project root2cd your-project34# Initialize Supabase5supabase init67# This creates:8# supabase/9# ├── config.toml (local configuration)10# ├── migrations/ (SQL migration files)11# ├── functions/ (Edge Functions)12# └── seed.sql (seed data for local dev)Expected result: A supabase/ directory is created in your project with config.toml and empty migrations/ and functions/ directories.
Start the local Supabase stack
Start the local Supabase stack
Run supabase start to launch a complete Supabase environment on your machine using Docker containers. This includes PostgreSQL, GoTrue (Auth), Storage, Realtime, PostgREST (API), Kong (gateway), and Supabase Studio. The first run downloads Docker images, which may take a few minutes. After startup, the CLI prints all local URLs and keys you need for development. Use these values in your .env.local file.
1# Start all local services2supabase start34# Output includes:5# API URL: http://localhost:543216# Studio URL: http://localhost:543237# DB URL: postgresql://postgres:postgres@localhost:54322/postgres8# anon key: eyJhbGciOiJIUzI1NiIs...9# service_role key: eyJhbGciOiJIUzI1NiIs...1011# Copy these to your .env.local:12# NEXT_PUBLIC_SUPABASE_URL=http://localhost:5432113# NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...1415# Check status anytime16supabase status1718# Stop the stack (data is preserved)19supabase stopExpected result: Docker containers start and the CLI prints local API URL, Studio URL, database connection string, anon key, and service role key.
Log in and link to your remote Supabase project
Log in and link to your remote Supabase project
To push migrations and deploy Edge Functions to your hosted Supabase project, you need to authenticate the CLI and link it to a specific project. Run supabase login to open a browser authentication flow. Then run supabase link with your project reference ID (found in the Dashboard URL or Project Settings). Linking stores the project reference locally so subsequent commands know which remote project to target.
1# Authenticate with your Supabase account2supabase login34# Find your project reference ID:5# Dashboard URL: https://supabase.com/dashboard/project/abcdefghijklmnop6# The ref is: abcdefghijklmnop78# Link to your remote project9supabase link --project-ref abcdefghijklmnop1011# You may be prompted for your database password12# (the one you set when creating the project)Expected result: The CLI is linked to your remote project. You can now run db push, functions deploy, and other remote commands.
Run essential CLI commands for daily development
Run essential CLI commands for daily development
With the CLI configured, here are the commands you will use most often. Create new migrations with supabase migration new, apply them locally with supabase migration up, and deploy to production with supabase db push. Generate TypeScript types from your schema to get full type safety in your application code. Serve Edge Functions locally with hot reload for development, and deploy them when ready.
1# Create a new migration2supabase migration new add_projects_table3# Edit the file in supabase/migrations/45# Apply migration locally6supabase migration up78# Reset local DB (reapply all migrations + seed)9supabase db reset1011# Push migrations to production12supabase db push1314# Pull remote schema as a local migration15supabase db pull1617# Generate schema diff after Dashboard changes18supabase db diff -f my_change1920# Generate TypeScript types21supabase gen types typescript --local > src/types/supabase.ts2223# Serve Edge Functions locally24supabase functions serve2526# Deploy an Edge Function27supabase functions deploy my-function2829# Set remote secrets30supabase secrets set STRIPE_KEY=sk_live_...Expected result: You can create migrations, generate types, serve functions, and deploy to production all from the command line.
Complete working example
1#!/bin/bash2# Complete Supabase CLI setup script3# Run this in your project root directory45# ============================================6# Step 1: Install the CLI7# ============================================89# macOS10brew install supabase/tap/supabase1112# Or via npm (recommended for team projects)13# npm install supabase --save-dev1415# Verify16supabase --version1718# ============================================19# Step 2: Initialize and start local stack20# ============================================2122supabase init23supabase start2425# Save the output — you need the API URL and anon key26# Create .env.local with:27# NEXT_PUBLIC_SUPABASE_URL=http://localhost:5432128# NEXT_PUBLIC_SUPABASE_ANON_KEY=<from supabase status>2930# ============================================31# Step 3: Link to remote project32# ============================================3334supabase login35supabase link --project-ref YOUR_PROJECT_REF3637# ============================================38# Step 4: Create your first migration39# ============================================4041supabase migration new create_initial_schema4243# Edit the migration file, then apply:44supabase migration up4546# ============================================47# Step 5: Generate TypeScript types48# ============================================4950mkdir -p src/types51supabase gen types typescript --local > src/types/supabase.ts5253# ============================================54# Step 6: Deploy to production55# ============================================5657supabase db push # Push migrations58supabase functions deploy # Deploy all Edge FunctionsCommon mistakes when configuring the Supabase CLI
Why it's a problem: Running supabase start without Docker Desktop running, which causes a connection error
How to avoid: Make sure Docker Desktop is installed, running, and has enough allocated memory (at least 4 GB). The CLI uses Docker to run all local services.
Why it's a problem: Forgetting to run supabase link before trying to deploy to production
How to avoid: Run supabase login followed by supabase link --project-ref your-ref to connect the CLI to your remote project. The project ref is in your Dashboard URL.
Why it's a problem: Editing the remote database directly in the Dashboard without pulling changes, causing migration drift
How to avoid: After making changes in the Dashboard, run supabase db diff -f describe_change to capture those changes as a local migration file. Then commit the migration to git.
Why it's a problem: Using the local anon key or URL in production environment variables
How to avoid: Local keys (from supabase status) only work with the local stack. Use the keys from Dashboard > Settings > API for your hosted project.
Best practices
- Install the CLI as a dev dependency via npm for team projects so everyone uses the same version
- Commit the entire supabase/ directory to git including config.toml, migrations, and Edge Functions
- Always create changes as migration files rather than editing the remote database directly
- Run supabase db reset regularly during development to verify your migrations apply cleanly from scratch
- Use supabase gen types typescript to generate type-safe client code after every schema change
- Add CLI commands as npm scripts in package.json for consistency across the team
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I just started a new project and need to set up the Supabase CLI for local development. Walk me through the complete setup: installing the CLI, initializing the project, starting local services, linking to my remote project, and creating my first migration.
Set up the Supabase CLI for a Next.js project. Initialize the supabase directory, start local services, create a migration for a users profile table, generate TypeScript types, and show me how to deploy everything to my hosted Supabase project.
Frequently asked questions
Do I need Docker to use the Supabase CLI?
Yes, Docker is required for supabase start which runs the local development stack. You do not need Docker for remote-only commands like supabase db push, supabase login, or supabase functions deploy.
How do I update the Supabase CLI?
With Homebrew: brew upgrade supabase. With npm: npm update supabase. Check the current version with supabase --version and compare with the latest release on GitHub.
Can I use the CLI on Windows?
Yes. Install via npm (npm install supabase --save-dev) or use Windows Subsystem for Linux (WSL) with the Homebrew method. Docker Desktop for Windows is required for the local stack.
What is the difference between supabase db push and supabase migration up?
supabase migration up applies migrations to your local database. supabase db push applies migrations to your remote (hosted) Supabase project. Always test locally first, then push to production.
How do I reset my local database to a clean state?
Run supabase db reset. This drops the local database, reapplies all migrations in order, and runs seed.sql. This is useful for testing that your migrations work correctly from scratch.
Can I use the Supabase CLI in CI/CD pipelines?
Yes. Use the npm installation method, set SUPABASE_ACCESS_TOKEN as an environment variable for authentication, and run supabase db push and supabase functions deploy in your pipeline.
Can RapidDev help me set up the Supabase CLI and local development workflow?
Yes. RapidDev can configure your local development environment, set up CI/CD pipelines with the Supabase CLI, and establish migration workflows for your team.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation