---

name: managing-supabase description: Supabase CLI for database management, Edge Functions, migrations, and local development. Use for managing Postgres databases, deploying serverless functions, and debugging Supabase projects.

Supabase CLI Skill

Table of Contents

1. Quick Reference
2. Critical: Avoiding Interactive Mode
3. Prerequisites
4. Authentication
5. CLI Decision Tree
6. Essential Commands
7. Local Development Ports
8. Common Workflows
9. Error Handling
10. Auto-Detection Triggers
11. Agent Integration
12. Quick Reference Card
13. Further Reading

---

Quick Reference

Supabase CLI enables local development, database migrations, Edge Functions deployment, and project management for Supabase projects.

---

Critical: Avoiding Interactive Mode

Supabase CLI can enter interactive mode which will hang Claude Code. Always use flags to bypass prompts:

Never use in Claude Code:

• supabase login without token (opens browser)
• Any command without --project-ref when not linked
• Interactive prompts for organization/region selection

Always include:

• SUPABASE_ACCESS_TOKEN environment variable for authentication
• --project-ref flag or pre-linked project
• Explicit flags for all configuration options

---

Prerequisites

Installation Verification

Copysupabase --version
# Expected: 2.x.x or higher

Installation Methods

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

---

Authentication

Environment Variables (CI/CD Required)

Token Generation

Generate tokens at: https://supabase.com/dashboard/account/tokens

Authentication Pattern for Claude Code

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

---

CLI Decision Tree

What do you need to do?

CopyProject 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.

---

Essential Commands

Project Setup

Database Commands

Migration Commands

Edge Functions Commands

Secrets Commands

For type generation, database inspection, storage, and project management commands, see REFERENCE.md.

---

Local Development Ports

---

Common Workflows

1. Initialize New Project

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

2. Create and Apply Migrations

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

3. Pull Remote Schema Changes

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

4. Deploy Edge Functions

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

5. Manage Secrets

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

6. Generate TypeScript Types

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

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

7. Debug Database Performance

Copy# 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 Handling

Common Errors and Solutions

Docker Issues

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

Migration Conflicts

Copy# 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.

---

Auto-Detection Triggers

This skill auto-loads when Supabase context is detected:

File-based triggers:

• supabase/config.toml in project
• supabase/ directory present
• SUPABASE_ACCESS_TOKEN in .env file

Context-based triggers:

• User mentions "Supabase"
• User runs supabase CLI commands
• Database migration discussions
• Edge Functions deployment

---

Agent Integration

Compatible Agents

Handoff Patterns

To Deep-Debugger: Slow query investigation, migration failures, Edge Function runtime errors

From Deep-Debugger: Schema problems requiring migrations, environment variable changes

---

Quick Reference Card

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

---

Further Reading

• REFERENCE.md - Complete command reference, regions, CI/CD integration, advanced patterns
• Supabase CLI Docs
• Local Development Guide