--- slug: supabase-cli-v3 published: 2026-11-04 change_type: breaking-change affected_products: - CLI page: https://supabase.com/changelog/supabase-cli-v3 --- # 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.]` 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.]` 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..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](https://supabase.com/docs/guides/local-development/cli/migrating-to-v3#quick-reference-for-ci) maps common v2 commands to their v3 form. 4. If you use `[remotes.]` 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](https://supabase.com/docs/guides/local-development/cli/migrating-to-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`, 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](https://github.com/supabase/cli/issues).