supabase-cli

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

Initial Project Setup

Initialize a new Supabase project:

```bash

supabase init

```

Start local development stack:

```bash

supabase start

```

Get connection details and API keys:

```bash

supabase status

```

Link to remote project:

```bash

supabase link --project-ref PROJECT_REF

```

---

Creating New Local Database

Start fresh local Supabase instance:

```bash

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:

```bash

supabase db reset

```

Reset without running seed data:

```bash

supabase db reset --no-seed

```

Checking Status

View all running services and connection details:

```bash

supabase status

```

Export connection details as environment variables:

```bash

supabase status -o env > .env.local

```

---

Creating Migrations

Method 1: Manual SQL File

Create new migration file:

```bash

supabase migration new create_users_table

```

Edit supabase/migrations/_create_users_table.sql:

```sql

CREATE TABLE users (

id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

email TEXT UNIQUE NOT NULL,

created_at TIMESTAMPTZ DEFAULT now()

);

```

Apply migration:

```bash

supabase db reset

```

Method 2: Auto-Generate from Diff

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

```bash

supabase db diff -f add_users_table

```

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

```bash

supabase db reset

```

Deploying Migrations

Preview changes before deployment:

```bash

supabase db push --linked --dry-run

```

Deploy to remote:

```bash

supabase db push --linked

```

Deploy with seed data:

```bash

supabase db push --linked --include-seed

```

Deploy with custom roles:

```bash

supabase db push --linked --include-roles

```

Pulling Remote Schema

Import existing remote schema to local:

```bash

supabase link --project-ref PROJECT_REF

supabase db pull initial_schema

supabase db reset

```

Pull specific schemas only:

```bash

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

---

TypeScript Types

Generate types from local database:

```bash

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

```

Generate from remote:

```bash

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

```

Generate specific schemas:

```bash

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

```

Other Languages

Generate Go types:

```bash

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

```

Generate Swift types:

```bash

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

```

Automation

Regenerate types after every schema change:

```bash

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

```

---

Getting Local Keys

View all local API keys:

```bash

supabase status

```

Extract keys to environment file:

```bash

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:

```bash

supabase login

```

Link to project:

```bash

supabase link --project-ref PROJECT_REF

```

Retrieve API keys:

```bash

supabase projects api-keys --project-ref PROJECT_REF

```

---

Using psql

Connect to local database:

```bash

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

```

Execute single query:

```bash

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

```

Run SQL file:

```bash

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

```

Connection Details

Get database URL from status:

```bash

supabase status

```

Extract only database URL:

```bash

supabase status | grep "DB URL"

```

Running Migrations Manually

Apply specific SQL file:

```bash

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

```

---

Standard Development Cycle

Daily workflow:

```bash

# 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:

```bash

# 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:

```bash

git pull

supabase db reset

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

```

Production Deployment

Safe deployment pattern:

```bash

# 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

```

---

Port Conflicts

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

```toml

[api]

port = 55321

[db]

port = 55322

[studio]

port = 55323

```

Then restart:

```bash

supabase stop

supabase start

```

Database in Bad State

Reset completely:

```bash

supabase stop

docker volume prune

supabase start

supabase db reset

```

Migration Conflicts

Pull remote changes first:

```bash

supabase db pull remote_changes

```

Resolve conflicts in migration files, then:

```bash

supabase db reset

supabase db push --linked

```

Type Mismatches

Regenerate types from current schema:

```bash

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

```

---

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

---

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:

```bash

# 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