majiayu000 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: npm install -g supabase
# 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:
- Go to https://supabase.com/dashboard/account/tokens
- Click "Generate new token"
- Give it a name (e.g., "CLI Development")
- 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
Create migration:
bun .claude/skills/supabase-cli/scripts/migration_new.ts add_user_rolesEdit the generated file in
supabase/migrations/Apply locally first:
bun .claude/skills/supabase-cli/scripts/migration_apply.ts --localCheck for drift:
bash .claude/skills/supabase-cli/scripts/check_drift.shApply to remote (with confirmation):
bun .claude/skills/supabase-cli/scripts/migration_apply.ts --remote --confirmUpdate TypeScript types:
bun .claude/skills/supabase-cli/scripts/update_types.ts
Edge Function Development
Scaffold new function:
bun .claude/skills/supabase-cli/scripts/func_new.ts webhook-handler --template webhookTest locally:
supabase functions serve webhook-handlerDeploy:
bun .claude/skills/supabase-cli/scripts/func_deploy.ts webhook-handler
Secret Management
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_List remote secrets:
python3 .claude/skills/supabase-cli/scripts/manage_secrets.py list
Local Development Cycle
Reset and reseed local database:
bun .claude/skills/supabase-cli/scripts/reset_local.tsRun 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
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 planningbrainstorm- Architecture decisions before migrationsbeautiful-code- TypeScript type generation quality