You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Supabase CLI v3 targets your local stack by default, asks before it changes a hosted project, and removes deprecated commands. Update your CI before you upgrade, or pin v2.
Supabase CLI v3.0.0 is the next major version of the Supabase CLI. npm, Homebrew, Scoop, the Linux packages, and supabase/setup-cli now install it by default. It changes which project a command runs against, when a command asks for confirmation, and where configuration values come from. Most pipelines that deploy with the CLI need a small change before they upgrade.
What changed
Database commands target your local stack by default. db push, db pull, db dump, migration list, gen types, and the storage commands run against the local stack unless you pass --remote. One --remote flag replaces --linked, --project-ref, and --db-url, which still work but are deprecated.
Every command that changes a hosted project asks for confirmation first, and the default answer is No. When the CLI can't ask, as in CI, the command fails unless you pass --yes. Piping y into a command no longer confirms it.
Flags and environment variables override config.toml, including [remotes.<name>] blocks. Every value resolves in the same order: flag, shell environment, project env files, config file, then default.
pg-delta is the default schema diff engine, so the SQL that db diff and db pull generate can change.
Deprecated commands, flags, config keys, and environment variables are removed. A removed command or flag exits with code 1 and prints its replacement. This includes the [inbucket] config section, which is now [local_smtp].
The CLI ships as a single supabase executable. The separate supabase-go executable is no longer installed.
Two smaller changes can affect a production project. config push now applies [auth.sms] enable_confirmations as written. secrets unset defaults to No and needs --all to remove every secret.
Why we made this change
In v2, some database commands defaulted to the linked project and others to the local stack, and four different flags chose a target. A command run without a flag could reach a production database. Many hosted changes ran without a confirmation, or with one that defaulted to Yes. Configuration had the same problem: config.toml beat environment variables for some settings and not for others.
v3 gives every command the same rules. Commands run locally unless you say otherwise, ask before any hosted change, and read every setting in one order. Defaults like these can only change in a major version, so v3 changes them together.
Who is affected
Anyone who runs the CLI in CI, in deploy scripts, or through an AI coding agent. Hosted changes that run unattended now need --yes, and database commands need --remote to reach your hosted project.
Projects created with supabase init before v2.108.0. Their supabase/config.toml has an [inbucket] section, so supabase start, stop, status, and the db commands fail until you rename it.
Projects that deploy with [remotes.<name>] blocks and also set SUPABASE_* environment variables. The variables now take precedence over the block, and config push pushes them.
Projects that edit supabase/schemas and then run db diff. Under pg-delta, use supabase db schema declarative sync instead.
Scripts that call removed commands or flags, or call supabase-go directly.
v3 changes the CLI only. Hosted projects, their data, and self-hosted Supabase are not affected.
What happens if you take no action
Nothing changes until you install v3. A pipeline that installs the latest CLI without pinning a version already runs v3. The most common failures are:
supabase start fails with [inbucket] in supabase/config.toml is no longer supported.
functions deploy, secrets set, config push, and db push fail in CI with HostedMutationConsentRequiredError.
db push without --remote targets the local stack. It fails when no local stack is running. If your job started one, it succeeds there and never reaches your hosted project.
Migration steps
Update to the latest v2 release and run your usual workflows, including CI. v2.122.0 and later warn about removed commands, flags, and config keys, and about commands whose default target changes in v3. Fix each warning.
Rename [inbucket] to [local_smtp] in supabase/config.toml, along with any [remotes.<name>.inbucket] block. The keys inside don't change. v2.108.0 and later already read [local_smtp], so you can do this before you upgrade.
Add --remote to every command that should reach your hosted project, and --yes to every hosted change that runs unattended. The quick reference for CI maps common v2 commands to their v3 form.
If you use [remotes.<name>] blocks, check the SUPABASE_* variables in CI and in your env files. Run supabase config diff before your first config push on v3.
If supabase/config.toml has no project_id, run supabase stop before you upgrade. Local container and volume names can change in v3.
Install v3 and work through the rest of the migration guide.
To upgrade later, pin v2 with npm install supabase@v2.stable --save-dev, brew install supabase/tap/supabase@2, scoop install supabase-v2-stable, or version: v2.stable on supabase/setup-cli@v3.
Rollout timeline
Date
Milestone
User action
2026-11-02
v3.0.0 released. npm, Scoop, the Linux packages, and supabase/setup-cli install v3 by default. v2.122.1 adds the v2.stable channels.
Follow the migration steps, or pin v2
2026-11-03
brew install supabase installs v3
Same as above
Ongoing
v2 receives security fixes and fixes for broken behavior, but no new features
Upgrade to v3 to get new features
If v3 breaks a workflow the migration guide doesn't cover, run supabase issue bug or open an issue.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Supabase CLI v3 targets your local stack by default, asks before it changes a hosted project, and removes deprecated commands. Update your CI before you upgrade, or pin v2.
Supabase CLI v3.0.0 is the next major version of the Supabase CLI. npm, Homebrew, Scoop, the Linux packages, and
supabase/setup-clinow install it by default. It changes which project a command runs against, when a command asks for confirmation, and where configuration values come from. Most pipelines that deploy with the CLI need a small change before they upgrade.What changed
db push,db pull,db dump,migration list,gen types, and thestoragecommands run against the local stack unless you pass--remote. One--remoteflag replaces--linked,--project-ref, and--db-url, which still work but are deprecated.--yes. Pipingyinto a command no longer confirms it.config.toml, including[remotes.<name>]blocks. Every value resolves in the same order: flag, shell environment, project env files, config file, then default.db diffanddb pullgenerate can change.[inbucket]config section, which is now[local_smtp].supabaseexecutable. The separatesupabase-goexecutable is no longer installed.Two smaller changes can affect a production project.
config pushnow applies[auth.sms] enable_confirmationsas written.secrets unsetdefaults to No and needs--allto remove every secret.Why we made this change
In v2, some database commands defaulted to the linked project and others to the local stack, and four different flags chose a target. A command run without a flag could reach a production database. Many hosted changes ran without a confirmation, or with one that defaulted to Yes. Configuration had the same problem:
config.tomlbeat environment variables for some settings and not for others.v3 gives every command the same rules. Commands run locally unless you say otherwise, ask before any hosted change, and read every setting in one order. Defaults like these can only change in a major version, so v3 changes them together.
Who is affected
--yes, and database commands need--remoteto reach your hosted project.supabase initbefore v2.108.0. Theirsupabase/config.tomlhas an[inbucket]section, sosupabase start,stop,status, and thedbcommands fail until you rename it.[remotes.<name>]blocks and also setSUPABASE_*environment variables. The variables now take precedence over the block, andconfig pushpushes them.supabase/schemasand then rundb diff. Under pg-delta, usesupabase db schema declarative syncinstead.supabase-godirectly.v3 changes the CLI only. Hosted projects, their data, and self-hosted Supabase are not affected.
What happens if you take no action
Nothing changes until you install v3. A pipeline that installs the latest CLI without pinning a version already runs v3. The most common failures are:
supabase startfails with[inbucket] in supabase/config.toml is no longer supported.functions deploy,secrets set,config push, anddb pushfail in CI withHostedMutationConsentRequiredError.db pushwithout--remotetargets the local stack. It fails when no local stack is running. If your job started one, it succeeds there and never reaches your hosted project.Migration steps
[inbucket]to[local_smtp]insupabase/config.toml, along with any[remotes.<name>.inbucket]block. The keys inside don't change. v2.108.0 and later already read[local_smtp], so you can do this before you upgrade.--remoteto every command that should reach your hosted project, and--yesto every hosted change that runs unattended. The quick reference for CI maps common v2 commands to their v3 form.[remotes.<name>]blocks, check theSUPABASE_*variables in CI and in your env files. Runsupabase config diffbefore your firstconfig pushon v3.supabase/config.tomlhas noproject_id, runsupabase stopbefore you upgrade. Local container and volume names can change in v3.To upgrade later, pin v2 with
npm install supabase@v2.stable --save-dev,brew install supabase/tap/supabase@2,scoop install supabase-v2-stable, orversion: v2.stableonsupabase/setup-cli@v3.Rollout timeline
supabase/setup-cliinstall v3 by default. v2.122.1 adds thev2.stablechannels.brew install supabaseinstalls v3If v3 breaks a workflow the migration guide doesn't cover, run
supabase issue bugor open an issue.Affected products: CLI
All reactions