supabase-cli

name	supabase-cli
description	Comprehensive guide for Supabase CLI usage covering database initialization, migrations, type generation, API key management, and direct query execution. Use this skill when working with Supabase local development, database schema management, or any CLI command usage.

Supabase CLI

Overview

This skill provides complete guidance for using Supabase CLI across all development workflows. It covers database initialization, migration management, type generation, API key retrieval, direct database access, and deployment strategies.

Use this skill when:

• Setting up new Supabase projects
• Managing database migrations
• Generating TypeScript types from database schema
• Retrieving API keys and connection details
• Executing SQL queries directly
• Troubleshooting local development issues
• Deploying schema changes to production

Quick Start

Initial Project Setup

Initialize a new Supabase project:

supabase init

Start local development stack:

supabase start

Get connection details and API keys:

supabase status

Link to remote project:

supabase link --project-ref PROJECT_REF

---

Database Initialization

Creating New Local Database

Start fresh local Supabase instance:

supabase init
supabase start

This creates:

• Local PostgreSQL database on port 54322
• Studio dashboard at http://localhost:54323
• API server on port 54321
• All Supabase services (Auth, Storage, Realtime, etc.)

Resetting Database

Reset database to clean state with all migrations applied:

supabase db reset

Reset without running seed data:

supabase db reset --no-seed

Checking Status

View all running services and connection details:

supabase status

Export connection details as environment variables:

supabase status -o env > .env.local

---

Migration Management

Creating Migrations

Method 1: Manual SQL File

Create new migration file:

supabase migration new create_users_table

Edit supabase/migrations/<timestamp>_create_users_table.sql:

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

Apply migration:

supabase db reset

Method 2: Auto-Generate from Diff

Make schema changes in Studio (http://localhost:54323), then generate migration:

supabase db diff -f add_users_table

Review generated file at supabase/migrations/<timestamp>_add_users_table.sql, then apply:

supabase db reset

Deploying Migrations

Preview changes before deployment:

supabase db push --linked --dry-run

Deploy to remote:

supabase db push --linked

Deploy with seed data:

supabase db push --linked --include-seed

Deploy with custom roles:

supabase db push --linked --include-roles

Pulling Remote Schema

Import existing remote schema to local:

supabase link --project-ref PROJECT_REF
supabase db pull initial_schema
supabase db reset

Pull specific schemas only:

supabase db pull -s public,extensions

Migration Best Practices

Always follow this workflow:

1. Create migration locally
2. Apply with supabase db reset
3. Generate types
4. Test application
5. Commit migration file
6. Deploy with supabase db push --linked --dry-run first
7. Deploy with supabase db push --linked

---

Type Generation

TypeScript Types

Generate types from local database:

supabase gen types typescript --local > src/lib/types/database.types.ts

Generate from remote:

supabase gen types typescript --linked > src/lib/types/database.types.ts

Generate specific schemas:

supabase gen types typescript --local --schema public,extensions > src/lib/types/database.types.ts

Other Languages

Generate Go types:

supabase gen types go --local > types/database.go

Generate Swift types:

supabase gen types swift --local --swift-access-control public > Types/Database.swift

Automation

Regenerate types after every schema change:

supabase db reset && supabase gen types typescript --local > src/lib/types/database.types.ts

---

API Key Management

Getting Local Keys

View all local API keys:

supabase status

Extract keys to environment file:

supabase status -o env > .env.local

Result includes:

• SUPABASE_URL - API endpoint
• SUPABASE_ANON_KEY - Client-side public key
• SUPABASE_SERVICE_ROLE_KEY - Server-side admin key
• DATABASE_URL - Direct database connection

Getting Remote Keys

Authenticate first:

supabase login

Link to project:

supabase link --project-ref PROJECT_REF

Retrieve API keys:

supabase projects api-keys --project-ref PROJECT_REF

---

Direct Database Access

Using psql

Connect to local database:

psql postgresql://postgres:postgres@localhost:54322/postgres

Execute single query:

psql postgresql://postgres:postgres@localhost:54322/postgres -c "SELECT * FROM users;"

Run SQL file:

psql postgresql://postgres:postgres@localhost:54322/postgres -f query.sql

Connection Details

Get database URL from status:

supabase status

Extract only database URL:

supabase status | grep "DB URL"

Running Migrations Manually

Apply specific SQL file:

psql postgresql://postgres:postgres@localhost:54322/postgres -f supabase/migrations/20230101_my_migration.sql

---

Common Workflows

Standard Development Cycle

Daily workflow:

# Morning: Start stack
supabase start

# Make schema changes in Studio or create migration
supabase migration new add_feature

# Apply changes
supabase db reset

# Regenerate types
supabase gen types typescript --local > src/lib/types/database.types.ts

# Test application
npm run dev

# Commit changes
git add supabase/migrations/ src/lib/types/database.types.ts
git commit -m "feat: add new feature schema"

# Deploy to production
supabase db push --linked --dry-run
supabase db push --linked

Team Collaboration

New developer setup:

# Clone repository
git clone REPO_URL

# Install CLI
npm install

# Login to Supabase
supabase login

# Start local development
supabase start

# Apply all migrations
supabase db reset

# Generate types
supabase gen types typescript --local > src/lib/types/database.types.ts

After pulling teammate's changes:

git pull
supabase db reset
supabase gen types typescript --local > src/lib/types/database.types.ts

Production Deployment

Safe deployment pattern:

# Link to production project
supabase link --project-ref PRODUCTION_REF

# Preview changes
supabase db push --linked --dry-run

# Review output carefully

# Deploy
supabase db push --linked

# Verify deployment
supabase db pull verify_deployment

---

Troubleshooting

Port Conflicts

If ports are already in use, edit supabase/config.toml:

[api]
port = 55321

[db]
port = 55322

[studio]
port = 55323

Then restart:

supabase stop
supabase start

Database in Bad State

Reset completely:

supabase stop
docker volume prune
supabase start
supabase db reset

Migration Conflicts

Pull remote changes first:

supabase db pull remote_changes

Resolve conflicts in migration files, then:

supabase db reset
supabase db push --linked

Type Mismatches

Regenerate types from current schema:

supabase gen types typescript --local > src/lib/types/database.types.ts

---

Command Reference

For complete CLI command reference with all flags and options, see references/cli-commands.md.

For detailed workflow examples and patterns, see references/workflows.md.

Most Used Commands

Setup:

• supabase init - Initialize project
• supabase login - Authenticate
• supabase link - Link to remote project
• supabase start - Start local stack
• supabase status - View connection details

Database:

• supabase db reset - Reset database with migrations
• supabase db diff -f NAME - Generate migration from diff
• supabase db push --linked - Deploy migrations
• supabase db pull - Import remote schema

Migrations:

• supabase migration new NAME - Create new migration
• supabase migration list - List all migrations

Types:

• supabase gen types typescript --local - Generate TypeScript types

Keys:

• supabase status - Get local keys
• supabase projects api-keys - Get remote keys

Cleanup:

• supabase stop - Stop local stack

---

Resources

references/cli-commands.md

Complete command reference with all flags, options, and examples for every Supabase CLI command. Load this when:

• Need detailed flag information for specific command
• Looking up exact syntax
• Exploring advanced command options

Search patterns:

# Find commands related to migrations
grep -i "migration" references/cli-commands.md

# Find commands for type generation
grep -i "gen types" references/cli-commands.md

# Find database commands
grep -i "supabase db" references/cli-commands.md

references/workflows.md

Comprehensive workflow guides covering:

• Initial setup patterns
• Schema development workflows
• Migration management strategies
• Type generation automation
• Team collaboration patterns
• CI/CD integration
• Troubleshooting common issues

Load this when:

• Planning complex workflow
• Setting up team collaboration
• Configuring CI/CD pipelines
• Solving workflow-specific problems
• Looking for best practices