Supabase CLI for database management, Edge Functions, migrations, and local development. Use for managing Postgres databases, deploying serverless functions, and debugging Supabase projects.
Manages Supabase projects using the CLI for database migrations, Edge Functions, and local development. Claude uses this when users mention Supabase or when `supabase/config.toml` is detected.
/plugin marketplace add FortiumPartners/ensemble/plugin install ensemble-infrastructure@ensembleThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdREFERENCE.mdexamples/ci-cd.example.yamlSupabase CLI enables local development, database migrations, Edge Functions deployment, and project management for Supabase projects.
Supabase CLI can enter interactive mode which will hang Claude Code. Always use flags to bypass prompts:
| Command | WRONG (Interactive) | CORRECT (Non-Interactive) |
|---|---|---|
| Login | supabase login | Use SUPABASE_ACCESS_TOKEN env var |
| Link project | supabase link | supabase link --project-ref <ref> |
| Create project | supabase projects create | supabase projects create <name> --org-id <id> --region <region> |
| Start local | supabase start | supabase start (non-interactive by default) |
| Deploy functions | supabase functions deploy | supabase functions deploy <name> --project-ref <ref> |
Never use in Claude Code:
supabase login without token (opens browser)--project-ref when not linkedAlways include:
SUPABASE_ACCESS_TOKEN environment variable for authentication--project-ref flag or pre-linked projectsupabase --version
# Expected: 2.x.x or higher
# npm (requires Node.js 20+)
npm install -g supabase
# Homebrew (macOS/Linux)
brew install supabase/tap/supabase
# Scoop (Windows)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
| Variable | Purpose | Required For |
|---|---|---|
SUPABASE_ACCESS_TOKEN | Personal access token | All remote operations |
SUPABASE_DB_PASSWORD | Database password | db push, db pull, link |
SUPABASE_PROJECT_ID | Project reference string | Linking without interactive prompt |
Generate tokens at: https://supabase.com/dashboard/account/tokens
# Set from project .env file
export SUPABASE_ACCESS_TOKEN="$(grep SUPABASE_ACCESS_TOKEN .env | cut -d= -f2)"
export SUPABASE_DB_PASSWORD="$(grep SUPABASE_DB_PASSWORD .env | cut -d= -f2)"
# All commands will use these automatically
supabase projects list
supabase link --project-ref <ref>
Project Setup
├── Initialize local project ──────────► supabase init
├── Link to remote project ────────────► supabase link --project-ref <ref>
├── Start local stack ─────────────────► supabase start
├── Stop local stack ──────────────────► supabase stop
└── Check status ──────────────────────► supabase status
Database Operations
├── Create migration ──────────────────► supabase migration new <name>
├── Apply migrations locally ──────────► supabase db reset
├── Push migrations to remote ─────────► supabase db push
├── Pull remote schema ────────────────► supabase db pull
├── Diff local vs remote ──────────────► supabase db diff --linked
└── Lint database schema ──────────────► supabase db lint
Edge Functions
├── Create new function ───────────────► supabase functions new <name>
├── Serve locally ─────────────────────► supabase functions serve
├── Deploy function ───────────────────► supabase functions deploy <name>
├── List deployed functions ───────────► supabase functions list
└── Delete function ───────────────────► supabase functions delete <name>
Secrets Management
├── Set secret ────────────────────────► supabase secrets set NAME=value
├── Set from file ─────────────────────► supabase secrets set --env-file .env
├── List secrets ──────────────────────► supabase secrets list
└── Remove secret ─────────────────────► supabase secrets unset NAME
Type Generation
├── Generate TypeScript types ─────────► supabase gen types typescript --linked
└── Generate from local ───────────────► supabase gen types typescript --local
Debugging
├── View container logs ───────────────► supabase logs (local)
├── Check slow queries ────────────────► supabase inspect db outliers
└── View blocking queries ─────────────► supabase inspect db blocking
For complete command reference including storage, project management, and all inspection commands, see REFERENCE.md.
| Command | Description | Key Flags |
|---|---|---|
supabase init | Initialize local project | --workdir |
supabase start | Start local development stack | -x (exclude services) |
supabase stop | Stop local stack | --no-backup |
supabase status | Show local container status | - |
supabase link | Link to remote project | --project-ref <ref> (required) |
| Command | Description | Key Flags |
|---|---|---|
supabase db reset | Reset local database | - |
supabase db push | Push migrations to remote | --dry-run, --include-seed |
supabase db pull | Pull schema from remote | --schema <name> |
supabase db diff | Diff schema changes | --linked, --local, -f <name> |
supabase db lint | Lint for schema errors | --linked, --level <warning|error> |
| Command | Description | Key Flags |
|---|---|---|
supabase migration new | Create new migration | <name> (required) |
supabase migration list | List migration history | --db-url <url> |
supabase migration up | Apply pending migrations | --local, --linked |
| Command | Description | Key Flags |
|---|---|---|
supabase functions new | Create new function | <name> (required) |
supabase functions serve | Serve locally | --env-file <path> |
supabase functions deploy | Deploy function(s) | --no-verify-jwt, --project-ref |
supabase functions delete | Delete function | <name> (required) |
| Command | Description | Key Flags |
|---|---|---|
supabase secrets set | Set secret(s) | NAME=value, --env-file <path> |
supabase secrets list | List secrets | --project-ref |
supabase secrets unset | Remove secret(s) | <NAME> |
For type generation, database inspection, storage, and project management commands, see REFERENCE.md.
| Service | Port | URL |
|---|---|---|
| API Gateway | 54321 | http://localhost:54321 |
| Database | 54322 | postgresql://postgres:postgres@localhost:54322/postgres |
| Studio | 54323 | http://localhost:54323 |
| Inbucket (Email) | 54324 | http://localhost:54324 |
# Create local project structure
supabase init
# Link to existing remote project
export SUPABASE_ACCESS_TOKEN="your-token"
supabase link --project-ref <project-ref>
# Start local development
supabase start
# Create new migration
supabase migration new add_users_table
# Edit migration file at supabase/migrations/<timestamp>_add_users_table.sql
# Apply locally
supabase db reset
# Push to remote
supabase db push
# Link project first
supabase link --project-ref <ref>
# Pull all schema changes
supabase db pull
# Or create migration from remote changes
supabase db pull --schema public
# Create new function
supabase functions new hello-world
# Edit supabase/functions/hello-world/index.ts
# Test locally
supabase functions serve
# Deploy to production
supabase functions deploy hello-world
# Deploy without JWT verification (for webhooks)
supabase functions deploy hello-world --no-verify-jwt
# Set individual secret
supabase secrets set STRIPE_KEY=sk_test_xxx
# Set from .env file
supabase secrets set --env-file .env.production
# List current secrets
supabase secrets list
# Remove secret
supabase secrets unset STRIPE_KEY
# From remote database
supabase gen types typescript --linked > src/types/database.ts
# From local database
supabase gen types typescript --local > src/types/database.ts
# Find slow queries
supabase inspect db outliers
# Check for blocking queries
supabase inspect db blocking
# Check cache hit ratios
supabase inspect db cache-hit
For advanced workflows including CI/CD integration and migration strategies, see REFERENCE.md.
| Error | Cause | Solution |
|---|---|---|
Error: You need to be logged in | Missing access token | Set SUPABASE_ACCESS_TOKEN env var |
Error: Project ref is required | No project linked | Use --project-ref or run supabase link |
Error: Cannot connect to Docker | Docker not running | Start Docker Desktop |
Error: Port 54321 already in use | Previous instance running | Run supabase stop first |
Error: Migration failed | SQL syntax error | Check migration file syntax |
# Check if Docker is running
docker info
# Clean up Supabase containers
supabase stop --no-backup
docker system prune -f
# Restart with fresh state
supabase start
# View migration status
supabase migration list
# Repair migration history
supabase migration repair --status reverted <version>
# Squash migrations if needed
supabase migration squash --version <timestamp>
For complete troubleshooting guide including permission issues and advanced debugging, see REFERENCE.md.
This skill auto-loads when Supabase context is detected:
File-based triggers:
supabase/config.toml in projectsupabase/ directory presentSUPABASE_ACCESS_TOKEN in .env fileContext-based triggers:
| Agent | Use Case |
|---|---|
deployment-orchestrator | Automated deployments, CI/CD |
infrastructure-developer | Database provisioning |
deep-debugger | Query analysis, performance debugging |
backend-developer | Database schema, Edge Functions |
postgresql-specialist | Advanced database operations |
To Deep-Debugger: Slow query investigation, migration failures, Edge Function runtime errors
From Deep-Debugger: Schema problems requiring migrations, environment variable changes
# Authentication (NEVER use supabase login in Claude Code)
export SUPABASE_ACCESS_TOKEN="xxx"
# Project setup
supabase init
supabase link --project-ref <ref>
supabase start
supabase stop
# Database
supabase migration new <name>
supabase db reset
supabase db push
supabase db pull
supabase db diff --linked
# Edge Functions
supabase functions new <name>
supabase functions serve
supabase functions deploy <name>
# Secrets
supabase secrets set KEY=value
supabase secrets list
supabase secrets unset KEY
# Types
supabase gen types typescript --linked > types.ts
# Debugging
supabase inspect db outliers
supabase inspect db blocking
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.