Breaking Change: Supabase CLI v3 is local by default and confirms hosted changes

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#

1. 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.
2. 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.
3. 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.
4. 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.
5. If supabase/config.toml has no project_id, run supabase stop before you upgrade. Local container and volume names can change in v3.
6. 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#

If v3 breaks a workflow the migration guide doesn't cover, run supabase issue bug or open an issue.