Web Apps & Prototypes
5 min read

Supabase CLI v3: Local by Default. What Breaks in CI and Deploy Scripts and How to Migrate

Colorful toy building blocks: a large tower in front of a wall with a glowing button, next to a small replica of the tower
Image: AI-generated
In short

Since November 2, 2026, npm, Scoop and the Supabase GitHub Action install CLI v3. Without a flag it targets the local database, and in pipelines it aborts changes to your hosted project unless you pass --yes. If you use CI or deploy scripts, pin v2 today and test the migration on your own schedule.

Supabase released CLI v3.0.0 on November 2, 2026, and the changelog entry flagging it as a breaking change followed on November 4. The CLI is the command line tool you use to ship database migrations, Edge Functions and secrets to Supabase from your laptop or from a pipeline. The update does not touch your hosted projects or their data. It changes what your scripts do.

What changes in Supabase CLI v3?

The CLI now targets your local development stack by default and asks before every change to a hosted project. The key points from the changelog:

  • Local by default: db push, db pull, db dump, migration list, gen types and the storage commands hit the local database unless you pass --remote.
  • One flag instead of three: --remote replaces --linked, --project-ref and --db-url. The old flags still work, but according to the migration guide --project-ref goes away in v4.
  • Confirmation that defaults to No: Every command that modifies a hosted project asks first. Without a terminal, which means in CI (your automated pipeline, for example in GitHub Actions), it fails unless you add --yes. Piping echo y into it no longer counts.
  • Removed commands: Old commands, flags and config keys exit with code 1 and name their replacement. [inbucket] in config.toml becomes [local_smtp].
  • New diff engine: pg-delta now generates the SQL for db diff and db pull. Generated migrations may look different from what you are used to.

Why could this hit you on your next run?

Because the install channels ship v3 without you doing anything. npm, Scoop, the Linux packages and the supabase/setup-cli action have delivered v3 since November 2, Homebrew since November 3. Without a version input, the action installs v3 unless a lockfile in the repo root (package-lock.json, pnpm-lock.yaml or bun.lock) pins the version, per the guide. If you call npx supabase without a fixed version, your next run pulls the new major version.

Which failures don't show up right away?

The loud errors are harmless: you will see HostedMutationConsentRequiredError for functions deploy, secrets set, config push or db push in your log. The dangerous ones are three silent cases:

Case What happens Fix
db push without --remote Runs against the local database. If your pipeline spins up a local stack for tests, the job turns green while the production database stays unchanged db push --yes --remote
SUPABASE_YES=1 in a .env file Only counts as a shell export. If the name appears in .env, .env.local or an environment specific file like .env.production in the working directory, even the shell export is ignored --yes directly on the command
Remote blocks like [remotes.staging] plus SUPABASE_* variables The variables now override the block, and config push sends their values to the project Run supabase config diff before your first config push

There is also a small detail with a big effect: secrets unset now only removes all secrets at once with --all. And according to the release notes, enable_confirmations = false under [auth.sms] now actually turns off phone confirmation on config push. If that line is in your file, your login flow changes.

What does this mean for AI coding agents?

Agents like Claude Code or Codex never get a prompt, not even in a terminal. The error message tells the agent to ask you before it adds --yes. Our take: this is the best part of the release. Until now, an agent needed no confirmation to change a hosted project. The guardrail only works, though, if nobody writes --yes into scripts or agent instructions across the board. Give it to the deploy step in your pipeline, not to the agent. For more on the risks of AI built apps, read our article on vibe coding.

Should you upgrade or stay on v2?

Pin today, migrate calmly. According to the changelog, v2 keeps getting security fixes and bug fixes, but no new features. Supabase has not announced an end date. Here is how to hold v2 in place:

  • npm: npm install supabase@v2.stable --save-dev
  • Homebrew: brew install supabase/tap/supabase@2
  • Scoop: scoop install supabase-v2-stable
  • GitHub Actions: version: v2.stable on supabase/setup-cli@v3

The migration in the order Supabase recommends:

  1. Move to the latest v2 and run every workflow, CI included. From v2.122.0 on, the CLI warns about everything that breaks in v3. Fix every warning.
  2. Rename [inbucket] to [local_smtp] in supabase/config.toml, including remote blocks like [remotes.staging.inbucket].
  3. Add --remote to every command that should reach the hosted project, and --yes to unattended hosted changes.
  4. Check SUPABASE_* variables in CI and in .env files, then run supabase config diff.
  5. If project_id is missing from config.toml, run supabase stop first, because container names can change.
  6. Install v3 and run your first deploy against a test project or a branch, not production.

What does this mean for your business?

You are affected if you talk to Supabase through scripts, pipelines or agents. If you only maintain your app in Lovable or in the Supabase dashboard and never use the CLI, there is nothing to do. If an agency or freelancer deploys your web app automatically, ask this week whether the version is pinned. After the switch, one quick check is enough: did the latest migration really land in the production database? That is exactly what a green checkmark no longer guarantees in v3. To see how customers can use your Supabase app from ChatGPT or Claude, read our post on the Supabase MCP server. And if you need help with Supabase web apps, take a look at our services.

Frequently asked questions

Does Supabase CLI v3 change anything in my hosted project or my data?

No. According to Supabase, hosted projects, their data and self-hosted Supabase are not affected. Only the way the CLI runs commands changes.

How can I tell which CLI version my pipeline is using?

Check the log of the install step in your pipeline to see which version was installed. If it shows 3.x, you are already on v3, even if you never touched the pipeline.

Can I use SUPABASE_YES instead of --yes?

Yes, but only as a shell export. It does not count in supabase/.env, and if a .env file in the working directory defines the variable, the CLI ignores the shell export too. Adding --yes to the command is the safe option.

How long will Supabase CLI v2 get updates?

Supabase has not named an end date. v2 gets security fixes and bug fixes but no new features, so a planned migration is worth it.

Sources

  1. Supabase: Breaking Change: Supabase CLI v3 is local by default and confirms hosted changes
  2. Supabase Docs: Migrating to Supabase CLI v3
  3. GitHub supabase/cli: Release v3.0.0
This article was created with AI.
Got a project in mind?

Tell us what you're planning. You'll get an honest assessment within 24 hours.

Got it! We will get back to you asap!
Whoopsie! Something went totally wrong here... Maybe just send an email to hi@blocksandcolors.de? Sorry!
Or email me directly: hi@blocksandcolors.de