{
  "slug": "supabase-cli-v3-local-targets-and-remote-selection-bd2abc070865",
  "title": "Supabase CLI v3 local targets and --remote selection",
  "tools": [
    "supabase"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-11-02T12:18:34.000Z",
  "announced_at": "2026-11-02T12:18:34.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When no target is supplied, the listed database, inspection, type-generation, and storage commands use the local stack. Add `--remote` for the linked project or `--remote=<ref|branch|postgres-url>` for another hosted target; with an operand, place it before bare `--remote`.",
    "examples": [
      "supabase db schema declarative generate --remote",
      "supabase db pull add_profiles --remote"
    ],
    "gotchas": [
      "Version: v3.0.0",
      "Non-interactive: Bare `--remote` in an unlinked checkout opens the project picker in an interactive terminal. Hosted mutations fail in non-interactive, JSON, stream-json, agent, or `-o json|yaml|toml|env` runs unless `--yes` or shell-exported `SUPABASE_YES` is set; piped `y` does not confirm. Target selection prints `Target: …` to stderr; JSON object results and error envelopes include a `target` object.",
      "--remote: Select the linked project; with `=<ref>`, `=<branch>`, or `=<postgres-url>`, select another project, linked-project branch, or database URL.",
      "--yes: Consent to hosted mutations in unattended runs.",
      "SUPABASE_PROJECT_ID: Selects which project bare `--remote` refers to; alone it does not select a hosted target.",
      "SUPABASE_YES: Shell-exported variable that consents to hosted mutations.",
      "`SUPABASE_PROJECT_ID` alone no longer selects a hosted project; it only determines which project bare `--remote` means.",
      "`--linked`, `--project-ref`, `--db-url`, and `gen types --project-id` are deprecated; they still work, print a warning naming the `--remote` form, and are hidden from help. `--local` does nothing and warns. These options cannot be combined with `--remote=<value>`.",
      "`--remote <word>` after a command that takes an operand fails with a “did you mean” error when the word looks like a branch name or project ref.",
      "`db query` rejects SQL passed both as an argument and with `--file`; an empty `--project-ref=` is an error.",
      "Bare `--remote` in an unlinked checkout opens the project picker in an interactive terminal."
    ]
  },
  "why_it_matters": "Run database, migration, inspection, type-generation, or storage commands against the local stack or a selected hosted target.",
  "before": "Use the prior target-selection options such as `--linked`, `--project-ref`, or `--db-url`; `gen types` without a target opened a project picker.",
  "sources": [
    "https://github.com/supabase/cli/releases/tag/v3.0.0"
  ],
  "rank": 0.99083,
  "review_state": "approved",
  "provenance": {
    "run_id": "daily-20261102-13",
    "verdict_id": "daily-20261102-13:daily-20261102-13-fd86132b8b07ac67-1:gate",
    "evidence_hash": "a9796195d3340f20a436d0ef0d56cdeae53d22854fb6678ab01b301b30f5c8a5"
  }
}