Supabase CLI v3: Local by Default, --yes Required

Supabase CLI v3.0.0 changes what an unflagged command does: database commands like db push now hit your local stack unless you pass --remote, and every change to a hosted project asks for confirmation, defaulting to No. It shipped on November 2, 2026 and is now what npm, Homebrew, Scoop, the Linux packages and the supabase/setup-cli GitHub Action install by default. If your CI or your AI coding agent installs the latest CLI without pinning, it is already on v3, and some deploys will fail or quietly do nothing.

What changed in Supabase CLI v3

Supabase lists six headline changes in its breaking-change notice:

• Local is the default target. db push, db pull, db dump, migration list, gen types and the storage commands run against the local stack unless you add --remote.
• One flag picks the target. --remote replaces --linked, --project-ref and --db-url. The old flags still work for now but are deprecated.
• Hosted changes need consent. Any command that changes a hosted project prompts first, and the default answer is No. Without a terminal, it fails unless you pass --yes. Piping y into the command no longer counts.
• One config order. Flags win, then shell environment variables, then project env files, then config.toml, then defaults. That includes [remotes.] blocks.
• pg-delta is the default diff engine, so SQL generated by db diff and db pull can change.
• Removed leftovers. Deprecated commands, flags and config keys exit with code 1 and print their replacement. The [inbucket] config section is now [local_smtp], and the separate supabase-go binary is gone.

Two quieter changes touch production settings: config push now applies [auth.sms] enable_confirmations exactly as written, and secrets unset defaults to No and needs --all to wipe every secret.

Why Supabase flipped the defaults

In v2 the CLI was inconsistent. Some database commands defaulted to the linked hosted project, others to the local stack, and four different flags chose the target. Supabase says plainly that a command run without a flag could reach a production database, and that many hosted changes ran with no prompt, or a prompt that defaulted to Yes.

That is a real risk in 2026, because the CLI is increasingly typed by agents, not people. A coding agent that runs supabase db push because a migration file looks finished should not be one keystroke from production. v3 makes production an explicit, visible choice in the command line. It is the same principle we covered in stopping AI coding agents from leaking secrets: make the dangerous path opt-in, not the default.

What breaks if you do nothing

Nothing changes until v3 is installed, but unpinned pipelines already have it. Per Supabase, the common failures are:

• supabase start fails with an error saying [inbucket] in supabase/config.toml is no longer supported. This hits projects created with supabase init before v2.108.0.
• functions deploy, secrets set, config push and db push fail in CI with HostedMutationConsentRequiredError.
• db push without --remote targets the local stack. With no local stack running it fails, which is the good outcome. If your job started a local stack for tests, the push succeeds there and never reaches your hosted database.

That last case is the one to worry about. A green CI run that never migrated production is harder to spot than a red one. Check your deploy logs for which database was actually touched after the first v3 run.

How to migrate a CI pipeline

Supabase's own sequence, condensed:

1. Upgrade to the latest v2 (v2.122.0 or later) and run your usual workflows, including CI. Those versions warn about removed flags and about commands whose default target changes. Fix every warning.
2. Rename [inbucket] to [local_smtp] in supabase/config.toml, including any [remotes.<name>.inbucket] block. v2.108.0 and later already read the new name, so this is safe before upgrading.
3. Add --remote to every command meant for the hosted project, and --yes to every hosted change that runs unattended.
4. If you use [remotes.] blocks, audit the SUPABASE_* variables in CI and env files, since they now win. Run supabase config diff before the first config push on v3.
5. If config.toml has no project_id, run supabase stop before upgrading, because local container and volume names can change.

Here is an illustrative before-and-after for a typical deploy job (not taken from Supabase's docs; adapt it to your own workflow):

v2

supabase db push --linked

supabase functions deploy

# v3 supabase db push --remote --yes supabase functions deploy --yes ```

Remote-only commands such as functions deploy, secrets set and config push already default to the linked project, so they need --yes in CI but not --remote. Per the local and hosted projects guide, --remote=<project-ref> targets a different project, --remote=<branch> a branch of the linked one, and a postgres:// URL works for database commands only.

If you are not ready: pin v2

You can stay on v2 while you test. Supabase offers v2.stable channels: npm install [email protected] --save-dev, brew install supabase/tap/supabase@2, scoop install supabase-v2-stable, or version: v2.stable on supabase/setup-cli@v3. Per the rollout table, v2 keeps getting security and broken-behavior fixes, but no new features.

Pinning is a stopgap, not a plan. Treat it as a week or two to run v2.122+ warnings, then move.

What it means for teams using AI coding agents

If an agent such as Claude Code or Codex CLI drives your Supabase workflow, v3 changes the agent's failure mode in a helpful way. An unattended hosted change now stops with an error instead of running. Two practical tips:

• Do not put --yes in the instructions or rules file you give the agent. Keep it in CI, where a human reviewed the change through a pull request.
• Expect agents trained on older docs to keep writing --linked and --db-url. They still work but are deprecated, so correct them in your agent instructions now.

For agents that manage several CLIs, our roundup of AI CLI coding agents covers which ones ask before running shell commands.

Pros and cons

• Pro: an unflagged command can no longer hit production, and hosted changes default to No.
• Pro: one target flag and one config precedence order are easier to reason about, for people and agents.
• Con: unpinned pipelines break on day one, and a pipeline that runs a local stack can silently skip the production migration.
• Con: environment variables now beating config.toml can push values you did not expect; supabase config diff is the safeguard.

Verdict

Upgrade, but on your schedule. Pin v2.stable today in any pipeline that installs the CLI unpinned, run the v2.122+ warnings, rename [inbucket], then switch to v3 with explicit --remote and --yes in CI only. The new defaults are the right call: production access should be something you write down, not something a missing flag gives you. Supabase is also on our radar for secret hygiene; see how GitHub now scans for Supabase keys.

Sources

• Supabase: Breaking Change, Supabase CLI v3 is local by default and confirms hosted changes
• Supabase docs: Running commands against local and hosted projects
• supabase/cli pull request 7186: warn before the v3 switch to a local default target
• Azeem Hassni: Supabase CLI 3.0 flips db push and pull to target local by default