# How to Configure the Supabase CLI - Tool: Supabase - Difficulty: Beginner - Time required: 15-20 min - Compatibility: Supabase CLI v1.100+, macOS, Linux, Windows (via WSL or npm) - Last updated: March 2026 ## TL;DR 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. ## Before you start - 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 ### 1. 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. ``` # macOS (recommended) brew install supabase/tap/supabase # Any OS via npm (add to your project) npm install supabase --save-dev # Run via npx if installed via npm npx supabase --version # Linux (direct download) brew install supabase/tap/supabase # or use npm method above # Verify installation supabase --version ``` **Expected result:** The CLI prints its version number, confirming successful installation. ### 2. 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. ``` # Navigate to your project root cd your-project # Initialize Supabase supabase init # This creates: # supabase/ # ├── config.toml (local configuration) # ├── migrations/ (SQL migration files) # ├── functions/ (Edge Functions) # └── 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. ### 3. 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. ``` # Start all local services supabase start # Output includes: # API URL: http://localhost:54321 # Studio URL: http://localhost:54323 # DB URL: postgresql://postgres:postgres@localhost:54322/postgres # anon key: eyJhbGciOiJIUzI1NiIs... # service_role key: eyJhbGciOiJIUzI1NiIs... # Copy these to your .env.local: # NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321 # NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs... # Check status anytime supabase status # Stop the stack (data is preserved) supabase stop ``` **Expected result:** Docker containers start and the CLI prints local API URL, Studio URL, database connection string, anon key, and service role key. ### 4. 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. ``` # Authenticate with your Supabase account supabase login # Find your project reference ID: # Dashboard URL: https://supabase.com/dashboard/project/abcdefghijklmnop # The ref is: abcdefghijklmnop # Link to your remote project supabase link --project-ref abcdefghijklmnop # You may be prompted for your database password # (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. ### 5. 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. ``` # Create a new migration supabase migration new add_projects_table # Edit the file in supabase/migrations/ # Apply migration locally supabase migration up # Reset local DB (reapply all migrations + seed) supabase db reset # Push migrations to production supabase db push # Pull remote schema as a local migration supabase db pull # Generate schema diff after Dashboard changes supabase db diff -f my_change # Generate TypeScript types supabase gen types typescript --local > src/types/supabase.ts # Serve Edge Functions locally supabase functions serve # Deploy an Edge Function supabase functions deploy my-function # Set remote secrets supabase 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 code example File: `supabase-cli-setup.sh` ```bash #!/bin/bash # Complete Supabase CLI setup script # Run this in your project root directory # ============================================ # Step 1: Install the CLI # ============================================ # macOS brew install supabase/tap/supabase # Or via npm (recommended for team projects) # npm install supabase --save-dev # Verify supabase --version # ============================================ # Step 2: Initialize and start local stack # ============================================ supabase init supabase start # Save the output — you need the API URL and anon key # Create .env.local with: # NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321 # NEXT_PUBLIC_SUPABASE_ANON_KEY= # ============================================ # Step 3: Link to remote project # ============================================ supabase login supabase link --project-ref YOUR_PROJECT_REF # ============================================ # Step 4: Create your first migration # ============================================ supabase migration new create_initial_schema # Edit the migration file, then apply: supabase migration up # ============================================ # Step 5: Generate TypeScript types # ============================================ mkdir -p src/types supabase gen types typescript --local > src/types/supabase.ts # ============================================ # Step 6: Deploy to production # ============================================ supabase db push # Push migrations supabase functions deploy # Deploy all Edge Functions ``` ## Common mistakes - **Running supabase start without Docker Desktop running, which causes a connection error** — undefined Fix: 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. - **Forgetting to run supabase link before trying to deploy to production** — undefined Fix: 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. - **Editing the remote database directly in the Dashboard without pulling changes, causing migration drift** — undefined Fix: 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. - **Using the local anon key or URL in production environment variables** — undefined Fix: 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 ## 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. --- Source: https://www.rapidevelopers.com/supabase-tutorial/how-to-configure-supabase-cli © RapidDev — https://www.rapidevelopers.com/supabase-tutorial/how-to-configure-supabase-cli