---

name: supabase-cli description: Comprehensive Supabase CLI reference for local development, migrations, Edge Functions, type generation, and deployment. Triggers on supabase, npx supabase, migrations, db push, db pull, db reset, edge functions, supabase start, supabase stop, supabase link, gen types, supabase deploy, local development stack, database branching, secrets management.

Supabase CLI Cheat Sheet

Purpose

Quick reference for all Supabase CLI commands used in local development, database migrations, Edge Functions, and deployment workflows.

When to Use

Activate this skill when:

• Running Supabase CLI commands
• Managing database migrations
• Working with Edge Functions
• Generating TypeScript types
• Deploying to production
• Troubleshooting local development stack

---

CRITICAL: Common Mistakes to AVOID

supabase db execute DOES NOT EXIST!

Copy# WRONG - This command doesn't exist!
supabase db execute --local "SELECT * FROM users;"

# The actual supabase db commands are:
# diff, dump, lint, pull, push, reset, start

To run SQL queries, use Docker + psql instead:

Copy# CORRECT - Use Docker to run SQL
docker exec supabase_db_crispy-crm psql -U postgres -d postgres -c \
  "SELECT column_name FROM information_schema.columns WHERE table_name = 'users';"

Docker -it flags fail in non-TTY environments

Copy# WRONG - Fails with "the input device is not a TTY"
docker exec -it supabase_db_crispy-crm psql -U postgres -c "SELECT 1;"

# CORRECT - Remove -t flag (or both -i and -t)
docker exec supabase_db_crispy-crm psql -U postgres -c "SELECT 1;"

Wrong container name

Copy# Find your container name first:
docker ps --filter "name=supabase_db"

# Then use the full name (includes project suffix):
docker exec supabase_db_crispy-crm psql -U postgres -c "..."

See WORKFLOWS.md for complete SQL execution guide.

---

Installation & Authentication

Copy# Install via npm
npm install -g supabase

# Or via Homebrew (macOS/Linux)
brew install supabase/tap/supabase

# Authenticate (opens browser)
supabase login

# Logout
supabase logout

---

Project Setup

Get project-id from: https://supabase.com/dashboard/project/<project-id>

---

Local Development Stack

Selective Start

Copy# Exclude services you don't need
supabase start -x studio,imgproxy

# Available: gotrue, realtime, storage-api, imgproxy, kong,
#            mailpit, postgrest, postgres-meta, studio,
#            edge-runtime, logflare, vector, supavisor

Default Local URLs

---

Database Migrations

Create Migrations

Copy# Create empty migration
supabase migration new <name>

# Diff local changes → migration file
supabase db diff -f <name>

# Diff against remote
supabase db diff --linked -f <name>

# Diff specific schema
supabase db diff --schema public -f <name>

Apply Migrations

Sync with Remote

Copy# Pull from remote → create migration
supabase db pull

# Pull specific schemas
supabase db pull --schema auth,storage

# Push to remote
supabase db push

# Preview push (dry run)
supabase db push --dry-run

Migration Management

---

Type Generation

Copy# From local database
supabase gen types typescript --local > src/types/supabase.ts

# From linked remote
supabase gen types typescript --linked > src/types/supabase.ts

# Specific schemas
supabase gen types typescript --local --schema public,auth

---

Edge Functions

Create & Manage

Copysupabase functions new <name>     # Create function
supabase functions list           # List all
supabase functions delete <name>  # Delete

Local Development

Copysupabase functions serve                    # Serve all
supabase functions serve <name>             # Serve one
supabase functions serve --env-file .env    # With env

Deploy

Copysupabase functions deploy <name>            # Deploy one
supabase functions deploy                   # Deploy all
supabase functions deploy --no-verify-jwt   # No JWT check

---

Secrets Management

Copysupabase secrets set KEY=value          # Set secret
supabase secrets set --env-file .env    # From file
supabase secrets list                   # List all
supabase secrets unset KEY              # Remove

---

Database Inspection

Copysupabase inspect db db-stats            # Database stats
supabase inspect db table-stats         # Table sizes
supabase inspect db index-stats         # Index usage
supabase inspect db bloat               # Find bloat
supabase inspect db long-running-queries # Slow queries
supabase inspect db locks               # Lock info

---

Storage

Copysupabase storage ls ss:///bucket/path       # List files
supabase storage cp ./file ss:///bucket/    # Upload
supabase storage cp ss:///bucket/file ./    # Download
supabase storage rm ss:///bucket/file       # Delete

---

Common Workflows

Fresh Local Start

Copysupabase init
supabase start
# Make changes in Studio (localhost:54323)
supabase db diff -f my_changes
supabase db reset  # Verify migrations

Deploy to Production

Copysupabase link --project-ref <id>
supabase db push              # Push migrations
supabase functions deploy     # Deploy functions

Regenerate Types After Schema Change

Copysupabase db reset
supabase gen types typescript --local > src/types/supabase.ts

---

Troubleshooting

Copysupabase status                      # Check health
supabase stop --no-backup && supabase start  # Full reset
supabase start --ignore-health-check # Force start

---

Reference Files

For detailed information, see:

• COMMANDS_REFERENCE.md - Complete command documentation with all flags
• CONFIG_REFERENCE.md - config.toml configuration options
• WORKFLOWS.md - Step-by-step workflow guides + mistake prevention
• TROUBLESHOOTING.md - Common errors and solutions
• CI_CD_PATTERNS.md - GitHub Actions workflows for migrations/deployment
• MCP_INTEGRATION.md - Using MCP tools alongside CLI

---

Hook Protection

This skill includes a PreToolUse hook that BLOCKS invalid commands:

• supabase db execute → Use Docker + psql
• supabase run/sql/query → Don't exist
• docker exec -it in non-TTY → Remove -t flag

The hook auto-detects your project ID from supabase/config.toml for correct container name suggestions.

---

Skill Type: Guardrail (blocks invalid commands) Line Count: ~320 (under 500-line limit)