feat(cli): warn before the v3 switch to a local default target by Coly010 · Pull Request #7186 · supabase/cli

Coly010 · 2026-10-15T12:33:19Z

Summary

v3 (CLI-2695, landing on next) makes the local stack the default target for every command that can run against either the local stack or a hosted project, with one --remote flag to reach a project. Today nothing tells you that's coming. This adds a warning on develop, without changing any default:

Warning: supabase db push will target the local database by default in the next major version. Pass --linked to keep targeting the linked project.

Printed on stderr, once, when one of these commands runs with no target selector and goes to the linked project: db push, db pull, db dump, migration fetch, migration list, migration repair, inspect db * (including the deprecated aliases, named as typed), inspect report, gen types, storage ls/cp/mv/rm. Storage says "the local Storage API".
Any of --linked, --local, --db-url, --project-ref (or gen types --project-id) silences it, in any form including --linked=false. SUPABASE_PROJECT_ID doesn't, since it won't select the project in v3.
gen types warns only once a project ref has resolved, so an unlinked run still prints just the existing "Must specify one of" error.
stdout, exit codes and the target itself are unchanged in every output format.

The opt-in target config key and SUPABASE_TARGET this PR previously added are gone; the v3 design drops them in favour of --remote.

Linked issue

Part of CLI-2695 (the non-breaking half for the current major).

Checklist

The PR title follows Conventional Commits.
Tests added or updated for the change.
From the repository root, pnpm check:all passes.

🤖 Generated with Claude Code

Add an optional top-level `target = "local" | "remote"` to the CLI config (and a `SUPABASE_TARGET` override). Commands that can run against either the local stack or the linked project follow it when no selector flag is given; an explicit selector always wins. Commands that default to the linked project today (db dump, migration list/repair, inspect db/report, gen types, storage ls/cp/mv/rm) print a single stderr deprecation warning when neither a selector nor a target is set, ahead of the default moving to local in the next major version. Behaviour is otherwise unchanged.

…o a remote target When a workspace target of remote picks the linked project, write one stderr line naming where it came from (SUPABASE_TARGET, supabase/.env, supabase/config.toml or config.json). A remote target also resolves --project-ref to the linked project; with no target or a local target the --project-ref behaviour is unchanged. A password given alongside a local workspace target now fails with the command's password-flag error instead of being dropped. The target is resolved inside the telemetry flush scope for lint, advisors and the migration commands, and the warning hint now reads "set target = "remote" in your Supabase config (or SUPABASE_TARGET=remote)". Adds handler-level coverage for the target branches across gen types, db diff, declarative generate, db reset, migration up/list/repair/squash, db lint/advisors/dump and storage, and replaces the tautological ProjectConfig tests with inputs that carry target.

github-actions

🤖 AI Review

Both independent reviews were available: Claude reported six findings and Codex reported none. Code inspection confirmed the warning's data-safety concern, incorrect environment-file provenance, and two stale descriptions. The telemetry finding and next-branch advisory were refuted. Tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	`apps/cli/src/command-internal/workspace-target.ts:176`	`data-safety`	claude	The deprecation warning recommends a workspace-wide remote target as a way to preserve one command's behavior, without explaining that this also retargets local-default commands. Following this advice can make existing `db reset --yes` automation drop schemas in the linked hosted database.
🟡 MINOR	`apps/cli/src/command-internal/workspace-target.ts:118`	`correctness`	claude	Every file-supplied SUPABASE_TARGET is attributed to supabase/.env, even when a different environment file supplied it.
⚪ NIT	`apps/cli/src/commands/db/reset/reset.handler.ts:132`	`ux`	claude	The --sql-paths warning incorrectly attributes remote selection only to --linked or --db-url when a workspace target can also select it.
⚪ NIT	`apps/cli/src/commands/db/diff/diff.handler.ts:431`	`documentation`	claude	The comment incorrectly says --use-pg-schema short-circuits before target resolution; resolution now precedes both delegation and the unsupported --project-ref guard.

Findings outside the diff

⚪ NIT apps/cli/src/commands/db/diff/diff.handler.ts:431 — The comment incorrectly says --use-pg-schema short-circuits before target resolution; resolution now precedes both delegation and the unsupported --project-ref guard.

Refuted findings (kept for transparency, not posted as review comments)

apps/cli/src/commands/storage/ls/ls.command.ts:63 (telemetry): Storage telemetry reports local: false when the workspace target selects the local stack because telemetryFlags retains flags.local instead of the effective target; cp, mv, and rm have the same pattern.
Refuted: The claimed local:false property is not emitted when --local is absent: buildFlagsMap includes only changedFlagNames and returns undefined when none exist. When --local is explicitly supplied, the workspace target is bypassed. Retaining parsed flag values also follows trusted/apps/cli/CLAUDE.md's telemetry convention; flags represent supplied options, not effective target state.
apps/cli-go/pkg/config/config.go:253 (next-impact): The Go Target field and pg-schema --linked forwarding will be discarded or require reconciliation when merging into next, which removes the Go sidecar.
Refuted: The next context supports removal of the Go implementation, but these compatibility additions can be discarded with that implementation. The TypeScript target resolver does not fundamentally depend on the sidecar. This is mechanical merge reconciliation, which does not meet the required fundamental-conflict threshold for next-impact findings.

Stats

Claude findings: 6 · Codex findings: 0 · Confirmed: 4 · Refuted: 2 · Uncertain: 0

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

…kspace target's reach

…flags

…rget is local

A malformed project .env* file or config no longer reads as an unset target. The DbConfigLoadError now surfaces before the command picks a connection, so a legacy linked-default command cannot fall back to the linked project when the file meant to select the local target is broken.

…develop-target-warning

…e next major db push, db pull, migration fetch/list/repair, db dump, inspect db/report, gen types and storage ls/cp/mv/rm still target the linked project when no selector is given. Print a stderr warning on those runs; passing --linked, --local, --db-url or --project-ref (--project-id for gen types) keeps the target the next major keeps and stays silent.

avallete

LGTM — selector detection checks out across all the commands (incl. --linked=false, deprecated inspect aliases, and db remote commit skipping it).

Non-blocking: outside gen types, the warning fires before the project ref resolves, so a bare db push / migration list / inspect db * / storage ls in an unlinked checkout prints the "will target local by default" warning right above the "not linked" error. Consider emitting it after ref resolution, like gen types does — or fine to leave as is.

A bare run in an unlinked checkout printed the "will target local by default" warning right above the not-linked error. The warning now fires only when a linked project ref is configured, from SUPABASE_PROJECT_ID or the link file. gen types keeps warning after its own ref resolution, which may come from the interactive picker.

…develop-target-warning # Conflicts: # apps/cli/src/commands/gen/types/types.handler.ts

Coly010 added 2 commits October 15, 2026 13:28

Coly010 requested a review from a team as a code owner October 15, 2026 12:33

github-actions Bot reviewed Oct 15, 2026

View reviewed changes

Comment thread apps/cli/src/command-internal/workspace-target.ts Outdated

Comment thread apps/cli/src/command-internal/workspace-target.ts Outdated

Comment thread apps/cli/src/commands/db/reset/reset.handler.ts

depthfirst-app Bot reviewed Oct 15, 2026

View reviewed changes

Comment thread apps/cli/src/commands/db/schema/declarative/generate/generate.handler.ts Outdated

Coly010 added 7 commits October 15, 2026 15:13

fix(cli): show the workspace target origin with forward slashes

bde1669

fix(cli): point the default-flip warning at --linked and flag the wor…

86686dd

…kspace target's reach

fix(cli): name the env file that supplied SUPABASE_TARGET

776bf43

fix(cli): stop attributing the db reset --sql-paths remote target to …

30a6d45

…flags

fix(cli): reject --password in db schema declarative generate when ta…

4e217e3

…rget is local

fix(cli): correct the db diff target-resolve ordering comment

840ca28

docs(cli): say the workspace target reads every project env file

4b6cd34

Coly010 changed the title ~~feat(cli): add opt-in workspace target and warn before v3 default flips (CLI-2695)~~ feat(cli): add a local/linked workspace target and warn before the v3 default flip Oct 15, 2026

depthfirst-app Bot reviewed Oct 15, 2026

View reviewed changes

Comment thread apps/cli/src/command-internal/workspace-target.ts Outdated

Coly010 mentioned this pull request Oct 15, 2026

feat(cli)!: one --remote flag, local target defaults and one hosted-mutation consent rule #7188

Merged

Coly010 added 4 commits October 16, 2026 11:09

Merge remote-tracking branch 'origin/develop' into columferry/cli-2695-…

378234a

…develop-target-warning

refactor(cli): drop the opt-in workspace target

9ef5312

Merge remote-tracking branch 'origin/develop' into columferry/cli-2695-…

6175135

…develop-target-warning

Coly010 changed the title ~~feat(cli): add a local/linked workspace target and warn before the v3 default flip~~ feat(cli): warn before the v3 switch to a local default target Oct 19, 2026

avallete approved these changes Oct 20, 2026

View reviewed changes

Coly010 added 2 commits October 20, 2026 11:34

Merge remote-tracking branch 'origin/develop' into columferry/cli-2695-…

79fcf3e

…develop-target-warning # Conflicts: # apps/cli/src/commands/gen/types/types.handler.ts

Coly010 added this pull request to the merge queue Oct 20, 2026

Merged via the queue into develop with commit 617be96 Oct 20, 2026
39 checks passed

Coly010 deleted the columferry/cli-2695-develop-target-warning branch October 20, 2026 11:03

Navigation Menu

Repository navigation

feat(cli): warn before the v3 switch to a local default target - #7186

feat(cli): warn before the v3 switch to a local default target#7186
Coly010 merged 16 commits into
developfrom
columferry/cli-2695-develop-target-warning

Coly010 commented Oct 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avallete left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Coly010 commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Linked issue

Checklist

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

🤖 AI Review

Findings

Findings outside the diff

Stats

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avallete left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Coly010 commented Oct 15, 2026 •

edited

Loading