Getting started with Supabase CLI for local development

Working with Supabase locally gives you more control and speeds up your development process. The Supabase CLI makes this possible with just a few commands. Let's see how you can set it up and start building with the full Supabase stack on your machine.

What is Supabase CLI?

Supabase CLI is a tool that lets you run the entire Supabase platform on your local computer. This includes PostgreSQL, Auth, Storage, Edge Functions, and Realtime features - all while you code.

With the CLI, you can:

• Run a local Supabase environment
• Create and manage database migrations
• Generate TypeScript types from your database schema
• Deploy changes to your Supabase projects
• Set up CI/CD workflows

Installing Supabase CLI

You have several options to install the CLI based on your operating system and preferences.

macOS

Using Homebrew:

brew install supabase/tap/supabase

Windows

Using Scoop:

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

Linux

For Debian/Ubuntu-based systems:

curl -fsS https://download.supabase.com/linux/apt/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/supabase-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/supabase-archive-keyring.gpg] https://download.supabase.com/linux/apt stable main" | sudo tee /etc/apt/sources.list.d/supabase.list > /dev/null
sudo apt-get update
sudo apt-get install supabase

npm or Bun

You can also install it using npm or Bun:

# npm
npm install -g supabase

# bun
bun install -g supabase

Setting up a local project

Before starting, make sure you have Docker installed. The Supabase CLI relies on Docker to run all the services locally.

Step 1: Create a new project

Create a folder for your project and navigate to it:

mkdir my-supabase-project
cd my-supabase-project

Step 2: Initialize Supabase

Run the following command to initialize a Supabase project:

supabase init

This creates a new supabase folder in your project with configuration files. You should commit this folder to your version control system.

Step 3: Start Supabase locally

Now start the Supabase services:

supabase start

The first time you run this, it will take a few minutes to download all the Docker images. Once everything is running, you'll see your local Supabase credentials in the terminal.

Working with your local Supabase

After starting Supabase, you'll get some important links:

Started supabase local development setup.
         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
        anon key: eyJh......
service_role key: eyJh......

Accessing Supabase Studio

Visit http://localhost:54323 to access Supabase Studio, the dashboard for your local project. Here you can:

• Create and manage tables
• Write and test SQL queries
• Set up authentication
• Configure storage buckets
• View realtime events

Connecting to your application

To connect your app to the local Supabase instance, use the API URL and keys from the terminal output:

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'http://localhost:54321'
const supabaseKey = 'your-anon-key'
const supabase = createClient(supabaseUrl, supabaseKey)

Managing database migrations

One of the powerful features of Supabase CLI is the ability to manage database changes with migrations.

Creating a migration

To create your first migration:

supabase migration new create_users_table

This creates a file in supabase/migrations with a timestamp. Open this file and add your SQL:

create table public.users (
  id uuid primary key default gen_random_uuid(),
  email text unique not null,
  name text,
  created_at timestamptz default now()
);

Apply migrations

To apply your migrations:

supabase db reset

This command resets your database and applies all migrations. It's great for development but don't use it in production!

Common CLI commands

Here are some useful Supabase CLI commands you'll use regularly:

# Stop the local Supabase stack
supabase stop

# Reset the database (applies all migrations)
supabase db reset

# Generate TypeScript types from your database
supabase gen types typescript > types/supabase.ts

# Show local environment details
supabase status

# Create a local database dump
supabase db dump -f dump.sql

Deploying to Supabase Cloud

After developing locally, you can deploy your changes to a Supabase cloud project.

Link to a remote project

First, login and link to your remote project:

supabase login
supabase link --project-ref your-project-ref

You can find your project reference in the URL of your Supabase dashboard.

Push database changes

To push your local migrations to the remote project:

supabase db push

This applies all your local migrations to the remote database, keeping them in sync.

Troubleshooting

Docker not running

If you see an error like "Cannot connect to the Docker daemon", make sure Docker is running on your machine.

Reset without backup

If you need to reset your local database completely:

supabase stop --no-backup
supabase start

This stops the Supabase stack without saving the current database state.

Conclusion

The Supabase CLI is an essential tool for anyone working with Supabase. It makes local development smoother and helps bridge the gap between development and production.

Start using the CLI today to:

• Speed up your development workflow
• Test changes safely in a local environment
• Manage database changes with version-controlled migrations
• Deploy with confidence to production

Give it a try and see how it can improve your Supabase development experience.