supabase-cli

Supabase CLI Skill

Complete CLI command reference for Supabase development.

Quick Reference

Task	Command
Install CLI	npm install supabase --save-dev
Login	supabase login
Init project	supabase init
Link to remote	supabase link --project-ref <ref>
Start local stack	supabase start
Stop local stack	supabase stop
Check status	supabase status
Create migration	supabase migration new <name>
Push to remote	supabase db push
Pull from remote	supabase db pull
Reset local DB	supabase db reset
Generate types	supabase gen types typescript --local > types.ts

Installation

# NPM (recommended for projects)
npm install supabase --save-dev
npx supabase [command]

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

# Scoop (Windows)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Prerequisites: Docker (required for local development)

Project Setup

Initialize Project

supabase init

Creates:

• supabase/config.toml - Configuration file
• supabase/migrations/ - Migration files
• supabase/seed.sql - Seed data

Link to Remote Project

supabase link --project-ref <project-ref>

Get project ref from: Dashboard → Project Settings → General

Local Development

Start Local Stack

supabase start

Starts:

• PostgreSQL database
• PostgREST API
• GoTrue Auth
• Realtime server
• Storage service
• Studio dashboard
• Inbucket (email testing)

Output URLs:

API URL: http://localhost:54321
DB URL: postgresql://postgres:postgres@localhost:54322/postgres
Studio URL: http://localhost:54323
Inbucket URL: http://localhost:54324

Stop Local Stack

# Stop and save data
supabase stop

# Stop and delete all data
supabase stop --no-backup

Check Status

supabase status

Shows URLs, API keys, and service status.

Database Commands

Create Migration

supabase migration new create_users_table

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

Generate Migration from Changes

# Make changes locally, then generate migration
supabase db diff -f my_schema_changes

# Diff against specific schemas
supabase db diff -f changes --schema public,extensions

Apply Migrations

# Apply pending migrations locally
supabase migration up

# Push to remote
supabase db push

# Preview what would be pushed
supabase db push --dry-run

Pull Remote Changes

supabase db pull

Creates migration from Dashboard changes.

Reset Local Database

supabase db reset

Recreates database and applies all migrations.

List Migrations

supabase migration list

Shows local vs remote migration status.

Rollback Migrations

# Rollback last n migrations
supabase migration down --count 1

# Rollback specific number
supabase migration down --count 3

Squash Migrations

# Combine multiple migrations into one
supabase migration squash --version 20240101000000

# Squash all migrations up to version
supabase migration squash --version <target_version>

Useful for cleaning up migration history before release.

Type Generation

Generate TypeScript Types

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

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

# From specific project
supabase gen types typescript --project-id "your-id" > database.types.ts

Edge Functions

Create Function

supabase functions new hello-world

Creates: supabase/functions/hello-world/index.ts

Serve Locally

# Serve all functions
supabase functions serve

# Serve specific function
supabase functions serve hello-world

# With env file and no JWT
supabase functions serve --env-file .env --no-verify-jwt

Deploy

# Deploy all functions
supabase functions deploy

# Deploy specific function
supabase functions deploy hello-world

# Deploy without JWT verification (for webhooks)
supabase functions deploy webhook-handler --no-verify-jwt

Test Function

curl -i --request POST \
  'http://localhost:54321/functions/v1/hello-world' \
  --header 'Authorization: Bearer <ANON_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Functions"}'

Secrets Management

# Set secret
supabase secrets set API_KEY=abc123

# Set multiple secrets
supabase secrets set API_KEY=abc123 DB_PASSWORD=secret

# Set from .env file
supabase secrets set --env-file .env

# List secrets
supabase secrets list

# Remove secret
supabase secrets unset API_KEY

Project Management

# List organizations
supabase orgs list

# List projects
supabase projects list

# Create project
supabase projects create <name> --org-id <id> --region <region>

# Delete project
supabase projects delete --project-ref <ref>

# Update remote config from local
supabase projects update-config

Database Inspection

# Cache hit ratio
supabase inspect db cache-hit --linked

# Unused indexes
supabase inspect db unused-indexes --local

# Table bloat
supabase inspect db bloat --linked

# Long running queries
supabase inspect db long-running-queries --linked

# Active connections
supabase inspect db role-connections --linked

Backup & Restore

Backup

# Dump roles
supabase db dump --linked -f roles.sql --role-only

# Dump schema
supabase db dump --linked -f schema.sql

# Dump data
supabase db dump --linked -f data.sql --use-copy --data-only

Restore

psql --single-transaction \
  --file roles.sql \
  --file schema.sql \
  --command 'SET session_replication_role = replica' \
  --file data.sql \
  --dbname [CONNECTION_STRING]

Common Flags

Flag	Description
--debug	Verbose output
--local	Use local database
--linked	Use linked remote
--project-ref <ref>	Specific project
--db-url <url>	Connection string
--dry-run	Preview without executing
-f <file>	Output to file

References

• local-development.md - Local stack setup
• migrations.md - Migration workflow
• config-toml.md - Configuration options