Supabase CLI

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:

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

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:

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:

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