Supabase CLI

CLI automation and operational tooling for Supabase development workflows. This skill provides scripts and utilities for common Supabase operations with built-in safety checks.

When to Use

Invoke when:

• Creating or applying database migrations
• Deploying Edge Functions
• Managing Supabase secrets
• Generating TypeScript types from schema
• Executing SQL with safety checks
• Checking for schema drift
• Validating environment configuration

Prerequisites

Required Tools

# Supabase CLI
brew install supabase/tap/supabase
# or: npx supabase / npm i supabase --save-dev (global npm install is NOT supported)

# Verify installation
supabase --version

Environment Variables

Before running scripts, validate credentials with:

python3 .claude/skills/supabase-cli/scripts/validate_env.py

Required variables:

Variable	Description	Required For
SUPABASE_URL	Project URL	All operations
SUPABASE_ANON_KEY	Public/anon key	Client operations
SUPABASE_SERVICE_ROLE_KEY	Service role key	Admin operations
POSTGRES_DB	Direct PostgreSQL URL	Migrations, SQL
SUPABASE_ACCESS_TOKEN	CLI access token	supabase link, db push, gen types

Getting the Supabase Access Token

The access token is required for CLI operations like linking projects, pushing migrations, and generating types.

How to get your token:

1. Go to https://supabase.com/dashboard/account/tokens
2. Click "Generate new token"
3. Give it a name (e.g., "CLI Development")
4. Copy the token (starts with sbp_)

How to use it:

Option 1: Store in .env.local (recommended for projects):

# .env.local (add to .gitignore!)
SUPABASE_ACCESS_TOKEN=sbp_your_token_here

Option 2: Export in terminal session:

export SUPABASE_ACCESS_TOKEN="sbp_your_token_here"

Option 3: Interactive login (opens browser):

supabase login

Link your project (required before pushing migrations):

# Extract project ref from your SUPABASE_URL (the subdomain)
# Example: https://abcdefghijkl.supabase.co → project ref is "abcdefghijkl"
supabase link --project-ref <your-project-ref>

Quick Reference

Task	Script	Example
Validate env	validate_env.py	python3 scripts/validate_env.py
New migration	migration_new.ts	bun scripts/migration_new.ts add-users
Apply migrations	migration_apply.ts	bun scripts/migration_apply.ts --local
Generate types	update_types.ts	bun scripts/update_types.ts
Run SQL safely	safe_sql_runner.ts	bun scripts/safe_sql_runner.ts --query "SELECT 1"
Check drift	check_drift.sh	bash scripts/check_drift.sh
New Edge Function	func_new.ts	bun scripts/func_new.ts my-function
Deploy function	func_deploy.ts	bun scripts/func_deploy.ts my-function
Sync secrets	secret_sync.py	python3 scripts/secret_sync.py --dry-run
Manage secrets	manage_secrets.py	python3 scripts/manage_secrets.py list
Reset local DB	reset_local.ts	bun scripts/reset_local.ts
Run DB tests	test_db.ts	bun scripts/test_db.ts
Scaffold RLS	scaffold_rls.ts	bun scripts/scaffold_rls.ts users --tenant

Workflow Patterns

Migration Workflow

1. Create migration:

   bun .claude/skills/supabase-cli/scripts/migration_new.ts add_user_roles
   

2. Edit the generated file in supabase/migrations/

3. Apply locally first:

   bun .claude/skills/supabase-cli/scripts/migration_apply.ts --local
   

4. Check for drift:

   bash .claude/skills/supabase-cli/scripts/check_drift.sh
   

5. Apply to remote (with confirmation):

   bun .claude/skills/supabase-cli/scripts/migration_apply.ts --remote --confirm
   

6. Update TypeScript types:

   bun .claude/skills/supabase-cli/scripts/update_types.ts
   

Edge Function Development

1. Scaffold new function:

   bun .claude/skills/supabase-cli/scripts/func_new.ts webhook-handler --template webhook
   

2. Test locally:

   supabase functions serve webhook-handler
   

3. Deploy:

   bun .claude/skills/supabase-cli/scripts/func_deploy.ts webhook-handler
   

Secret Management

1. Sync .env to remote:

   python3 .claude/skills/supabase-cli/scripts/secret_sync.py --prefix APP_ --dry-run
   python3 .claude/skills/supabase-cli/scripts/secret_sync.py --prefix APP_
   

2. List remote secrets:

   python3 .claude/skills/supabase-cli/scripts/manage_secrets.py list
   

Local Development Cycle

1. Reset and reseed local database:

   bun .claude/skills/supabase-cli/scripts/reset_local.ts
   

2. Run database tests:

   bun .claude/skills/supabase-cli/scripts/test_db.ts
   

RLS Policy Scaffolding

Generate RLS policies for new tables:

# Standard user-based policies
bun .claude/skills/supabase-cli/scripts/scaffold_rls.ts products

# Multi-tenant policies (for restaurant_id based isolation)
bun .claude/skills/supabase-cli/scripts/scaffold_rls.ts orders --tenant

# Output to migration file
bun .claude/skills/supabase-cli/scripts/scaffold_rls.ts menu_items --tenant --output supabase/migrations/015_rls.sql

Safety Guidelines

SQL Classification

Scripts classify SQL statements by risk level:

Level	Statements	Behavior
Safe	SELECT, EXPLAIN, SHOW	Execute immediately
Write	INSERT, UPDATE, DELETE, ALTER, CREATE	Require transaction wrap
Dangerous	DROP, TRUNCATE, DELETE (no WHERE)	Require --confirm flag

Remote Operation Rules

The following require explicit --confirm flag:

• Migrations to remote database
• Dangerous SQL on remote
• Secret deletion

Pre-Deployment Checks

Before deploying Edge Functions:

• TypeScript compilation check
• Function file existence validation
• Size limits verification

Self-Healing

The CLI surface changes (e.g. db execute was removed in favor of db query; db push targets the linked REMOTE by default). On any error: supabase <command> --help → if unclear, WebFetch https://supabase.com/docs/reference/cli/supabase-<command> (dashes join subcommands) → adjust → re-run.

Refusal Pattern

REFUSED: `supabase <command>` is destructive against the linked remote project.
  I won't skip confirmation. Either (1) confirm the target explicitly
  (--local vs --linked), or (2) run it in the Supabase Dashboard.

References

For detailed information:

Topic	Reference File
CLI commands	references/cli-commands.md
Migration patterns	references/migration-patterns.md
Troubleshooting	references/troubleshooting.md

Error Handling

When scripts detect missing credentials, they output in this format:

MISSING: SUPABASE_SERVICE_ROLE_KEY
ASK_USER: Please provide your Supabase Service Role Key.
LOCATION: Dashboard > Project Settings > API > service_role key

Claude should parse this and use AskUserQuestion to prompt for the missing credential.

Integration

Pairs with:

• /plan-feature - Database schema design during feature planning
• brainstorm - Architecture decisions before migrations
• beautiful-code - TypeScript type generation quality