Supabase CLI Skill

•Quick Reference
•Critical: Avoiding Interactive Mode
•Prerequisites
•Authentication
•CLI Decision Tree
•Essential Commands
•Local Development Ports
•Common Workflows
•Error Handling
•Auto-Detection Triggers
•Agent Integration
•Quick Reference Card
•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:

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)
•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

bash

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

Installation Methods

bash

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

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

Token Generation

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

Authentication Pattern for Claude Code

bash

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

code

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.

Essential Commands

Project Setup

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)

Database Commands

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>`

Migration Commands

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`

Edge Functions Commands

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)

Secrets Commands

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.

Local Development Ports

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`

Common Workflows

1. Initialize New Project

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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

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

Docker Issues

bash

# 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

bash

# 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

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

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

bash

# 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

managing-supabase

Supabase CLI Skill

Table of Contents

Quick Reference

Critical: Avoiding Interactive Mode

Prerequisites

Installation Verification

Installation Methods

Authentication

Environment Variables (CI/CD Required)

Token Generation

Authentication Pattern for Claude Code

CLI Decision Tree

What do you need to do?

Essential Commands

Project Setup

Database Commands

Migration Commands

Edge Functions Commands

Secrets Commands

Local Development Ports

Common Workflows

1. Initialize New Project

2. Create and Apply Migrations

3. Pull Remote Schema Changes

4. Deploy Edge Functions

5. Manage Secrets

6. Generate TypeScript Types

7. Debug Database Performance

Error Handling

Common Errors and Solutions

Docker Issues

Migration Conflicts

Auto-Detection Triggers

Agent Integration

Compatible Agents

Handoff Patterns

Quick Reference Card

Further Reading