Supabase CLI Operations
Overview
The Supabase CLI covers local dev, database management, migrations, edge functions, storage, secrets, type generation, and remote project management. Most remote operations require authentication and project linking. Always check prerequisites before running commands.
Prerequisites Check Flow
Before running any command, verify these in order:
digraph prereqs { "Operation requested" -> "Needs remote access?"; "Needs remote access?" -> "Check auth" [label="yes"]; "Needs remote access?" -> "Needs local init?" [label="no"]; "Check auth" -> "supabase login" [label="not authed"]; "Check auth" -> "Needs project link?" [label="authed"]; "supabase login" -> "Needs project link?"; "Needs project link?" -> "supabase link --project-ref <ref>" [label="not linked"]; "Needs project link?" -> "Needs local init?" [label="linked"]; "supabase link --project-ref <ref>" -> "Needs local init?"; "Needs local init?" -> "supabase init" [label="no config.toml"]; "Needs local init?" -> "Needs containers?" [label="has config.toml"]; "supabase init" -> "Needs containers?"; "Needs containers?" -> "supabase start" [label="local dev command"]; "Needs containers?" -> "Run command" [label="no"]; "supabase start" -> "Run command"; }
Quick checks:
-
Auth status: supabase projects list (errors if not logged in)
-
Linked: look for .supabase/ directory or supabase/config.toml with project_id
-
Local running: supabase status
Common Workflows
New Project Setup (Local Dev)
supabase init # creates supabase/ directory supabase login # authenticate supabase link --project-ref <ref> # link to remote project supabase start # start local containers
First Migration
supabase migration new create_users_table
edit supabase/migrations/<timestamp>_create_users_table.sql
supabase db reset # apply locally supabase db push # push to remote (requires link)
Deploy Edge Function
supabase functions new <name> # scaffold locally
edit supabase/functions/<name>/index.ts
supabase functions serve <name> # test locally supabase functions deploy <name> # deploy to remote
Pull Remote Schema + Generate Types
supabase db pull # pulls remote schema as migration supabase gen types --lang typescript --project-id <ref> > types/supabase.ts
Secrets Management
supabase secrets list supabase secrets set MY_KEY=value supabase secrets unset MY_KEY
Operation Categories
Category Key Commands
Auth login , logout
Project Setup init , link , unlink , bootstrap
Local Dev start , stop , status , services
Database db diff , db dump , db lint , db pull , db push , db reset , db start
Migrations migration new/list/up/down/fetch/repair/squash
Edge Functions functions new/list/deploy/delete/download/serve
Secrets secrets list/set/unset
Storage storage ls/cp/mv/rm
Type Generation gen types , gen bearer-jwt , gen signing-key
Inspection inspect db , inspect report
Backups backups list/restore
Branches branches create/list/get/delete/pause/unpause/update
Projects projects create/list/delete/api-keys
Orgs orgs create/list
Config config push
Domains/Vanity domains * , vanity-subdomains *
SSL/Network ssl-enforcement * , network-bans * , network-restrictions *
SSO sso add/list/show/info/update/remove
Postgres Config postgres-config get/update/delete
Snippets snippets list/download
Seed seed buckets
Testing test db , test new
For full flags and examples, see references/cli-map.md .
Common Mistakes
Mistake Fix
Running db push without linking supabase link --project-ref <ref> first
functions deploy fails with auth error supabase login then retry
Local dev commands fail Check supabase status ; run supabase start if containers are down
db pull overwrites manual migrations Use db diff first to review changes
gen types without project ID Pass --project-id <ref> or use --local for local schema
Migration conflicts after db pull
Use migration repair to reconcile history
Getting Your Project Ref
supabase projects list # shows all projects with IDs