feat(cli)!: resolve config values as flags > env > config.toml > defaults

[Coly010]

Summary

Every config value now resolves in one order, in every command:

explicit flag > shell env > project env files > config (config.json over config.toml, a matched [remotes.*] block over the base) > default

Project env files are .env.<SUPABASE_ENV>.local, .env.local, .env.<SUPABASE_ENV> and .env. They are read from supabase/ and then the project root, and SUPABASE_ENV defaults to development.

Before this change, each command family overlaid flags, env and remotes by hand, and the families disagreed:

• A matched [remotes.*] block beat an explicit SUPABASE_* variable.
• Some commands ignored variables that others honoured.
• config diff and config push could see different values.
• --password was silently dropped when combined with --db-url.

ADR 0001 already defined this order, so this is mostly making the code actually follow it.

Closes CLI-1885, closes CLI-2214. The decisions are recorded in ADR 0031.

How it works

Before, every command decided for itself where a setting came from, and they didn't agree. Now one service answers "what's the value of X?" for every command, and it always asks the same sources in the same order.

The problem

A setting like "should db push seed?" can come from five places:

1. a flag you typed (--include-seed)
2. your shell (export SUPABASE_DB_SEED_ENABLED=true)
3. a project env file (supabase/.env, .env.local, ...)
4. config.toml, where a matching [remotes.staging] block beats the base [db.seed]
5. a built-in default

Each command family used to walk that list by hand, in its own order, with its own parser. So db push and start could look at the same setting and get different answers, a remote block could beat your shell env in one command but not another, and config diff could show something different from what config push would send.

The service: CliConfigValues

Think of it as a librarian. You don't go into the stacks yourself; you ask the librarian. It checks the five shelves in one fixed order and hands you the first answer it finds, with a note saying which shelf it came from.

flag  >  shell env  >  project .env*  >  config.toml (remote over base)  >  default

A command uses it in three steps.

1. Load the resolved config once per run.

const configValues = yield* CliConfigValues
const resolvedConfig = yield* configValues.load({ workdir, projectRef })

This reads the flags, the env and the env files, parses config.toml, picks the matching [remotes.*] block, applies the order above and validates the whole config. If anything is invalid (for example SUPABASE_STUDIO_PORT=abc), the command stops here, and the error names where the bad value came from.

2. Ask for a value by key.

const enabled = yield* resolvedConfig.get(CliConfigKeys.db.seed.enabled)
// enabled.value  → true
// enabled.origin → { tier: "shell", envName: "SUPABASE_DB_SEED_ENABLED" }

You get the value plus its origin. That origin is what lets the CLI say things like SUPABASE_AUTH_SITE_URL (shell) overrides auth.site_url in [remotes.staging] or (from SUPABASE_API_MAX_ROWS in supabase/.env).

3. Bind flags to keys instead of reading them by hand.

// push.command.ts
includeSeed: CliConfigKeys.db.seed.enabled.flag({
  name: "include-seed",
  description: "Include seed data from your config.",
}),

The flag isn't a separate boolean the handler has to remember to merge in. It is declared as the flag tier of db.seed.enabled, so the resolved config already knows about it.

Where the keys come from

CliConfigKeys is generated from the config schema (CliConfigSchema). Every leaf in config.toml becomes a key with:

• its path: db.seed.enabled
• its env name: SUPABASE_ plus the path in upper snake case, so SUPABASE_DB_SEED_ENABLED
• a parser chosen from its type: boolean, port, list, and so on

Nobody writes the 360 or so keys by hand. Add a field to the schema and it gets an env override and a parser for free. The only hand-written parts are exceptions, such as codec overrides, exclusions and section gates like "SMTP env vars only apply if [auth.email.smtp] exists".

A worked example

[db.seed]
enabled = true

[remotes.staging]
project_id = "abc123"

[remotes.staging.db.seed]
enabled = false

SUPABASE_DB_SEED_ENABLED=true supabase db push --project-ref abc123 --include-seed

Shelf	Says	Used?
flag --include-seed	true	✅ wins
shell SUPABASE_DB_SEED_ENABLED	true
project .env*	unset
[remotes.staging.db.seed]	false
[db.seed] (base)	true
default	false

Seeding is on, from the flag. Without the flag, the shell value wins (still on, origin shell). Before this PR, the remote block's false would have beaten the shell variable, which is the headline breaking change. And because seeding is on for a project that matched a remote block that doesn't itself turn seeding on, the CLI asks for confirmation before seeding.

How it relates to config.toml

config.toml isn't replaced. It's shelf 4. The @supabase/config package still parses it, merges the matching remote and decodes it. The service calls those package stages and layers flags and env on top, and commands can no longer call the package loaders directly.

The resolved config gives two views of the whole config:

• resolvedConfig.loaded: what you declared (file plus flags and env), with no defaults. config push and config diff use this, so push never sends a default you didn't write.
• resolvedConfig.materialized: the same with defaults applied. Used by things that need a complete config to run, like start, local Docker and stack.

What stops this drifting back

• A guard test fails if any file outside the service mentions a SUPABASE_* config env name or imports the package config loaders.
• oxlint bans process.env and Bun.env across the CLI.
• A command that reads config without wiring the service in fails tsc.
• A contract test checks every key in the registry against the order.

Design

It's a big diff, sorry - but most of it is commands moving onto the new service. The interesting parts are apps/cli/src/config/cli-config-*.ts, the guard tests in code-structure.unit.test.ts and ADR 0031. If you disagree with any of the behaviour calls in the table below, that's totally fine, I'd rather we settle them here than after next ships.

• One service. CliConfigValues is the only service that resolves values.
  • load({ workdir, projectRef }) returns a memoised ResolvedCliConfig.
  • resolvedConfig.get(key) returns the value and the tier it came from.
  • resolvedConfig.loaded is the declared config: file, flags and env, with no defaults. config push and config diff use it.
  • resolvedConfig.materialized is the declared config with defaults applied.
  • The whole config is decoded on load, so an invalid value fails the command before it does anything.
• Generated key registry. The registry is generated from CliConfigSchema. Each leaf gets the env name SUPABASE_ + its upper-snake path, and a codec derived from its type. Section gates, codec overrides and exclusions are hand-written annotations.
• Flags. A flag binds to a key with key.flag(...), so "explicitly passed" is part of the type rather than a convention. If two flags set the same key to different values, the first load fails with CliConfigFlagConflictError.
• Package stages. @supabase/config/internal exposes the pipeline stages: parse, merge a selected remote, decode. Only the foundation calls them.
• Guardrails:
  • A code-structure test fails on:
    • registry env names written as string literals outside the foundation files
    • imports of the package loaders (loadCliConfig, resolveCliConfigSubtree, loadCliProjectEnvironment) outside the foundation
    • the old overlay helpers
    • registry-backed flags declared without key.flag
  • oxlint bans process.env, Bun.env, globalThis.process and env imported from node:process across apps/cli/src.
  • A command that reads config values without withCliConfigFlags fails tsc.
• Visibility:
  • When a shell or project env value beats a value that the matched [remotes.*] block sets, the CLI prints one WARN per key.
  • --debug lists the origin of every non-default value.
  • config push labels env-sourced rows and prints a one-line summary of them, even with --yes.
• Exceptions kept on purpose:
  • CommandSettings reads SUPABASE_PROJECT_ID from the shell only.
  • experimental-feature.ts ignores remotes and env files, because it runs before the project is known.
  • db.password has no env tier.
  • secrets set tolerates an invalid unrelated value, so a broken key doesn't block rotating a secret.
  • The service-role key isn't scoped to the linked project; only the database password is.

Behaviour changes

Change	Before	Now
Env vs matched remote	A [remotes.*] block beat SUPABASE_* variables for the keys it set	Flags and env beat the block, with a WARN for each key they override
SUPABASE_PROJECT_ID and a matched remote	The remote's project_id named local Docker resources	SUPABASE_PROJECT_ID wins
--include-seed and enabled = false	A remote's or the base's [db.seed] enabled = false won	--include-seed, --sql-paths or SUPABASE_DB_SEED_ENABLED=true override it. db push still seeds only with --include-seed
Seed confirmation	None	db push and db reset --linked ask before seeding a project that matched a [remotes.*] block, unless that block itself sets db.seed.enabled = true. --yes or SUPABASE_YES confirms. A non-interactive run without it exits 1 with SeedConsentRequiredError before applying anything
--password with --db-url or --local	Silently ignored by db push, db pull, db dump and db schema declarative generate	Exits 1 with a message saying where the password goes instead. migration list and migration repair now also reject --local. migration squash targets the local database unless you pass --linked, so squash -p needs --linked. An empty -p "" counts as not passed
SUPABASE_DB_PASSWORD for another project	Sent to whichever project was targeted	Withheld when the target differs from the linked project. A notice names both refs and says a temporary login role is used instead. Unlinked directories and same-project targets keep using the variable
db diff --use-pg-delta=false	No effect against env or config	Turns pg-delta off over env and config. The stack backend always uses pg-delta
db pull --use-pg-delta (hidden, deprecated)	Selected the declarative export only	Also turns pg-delta on for the run, so the export leaves [db.migrations].schema_paths alone
SUPABASE_EXPERIMENTAL_PGDELTA_ENABLED	Not read	Overrides [experimental.pgdelta].enabled like any other key, so false selects migra for the run. SUPABASE_EXPERIMENTAL_PG_DELTA stays ignored
Boolean variables	Each reader had its own parser (SUPABASE_EXPERIMENTAL_STACK took 0/1 only)	One grammar everywhere: 1, t, T, true, True, TRUE or 0, f, F, false, False, FALSE. Anything else, including mixed case like tRue, fails the command
Invalid config value	Failed only the commands that read it, with a command-specific error	Fails every command that loads the config (including stop and services) with CliConfigValueError, naming the variable or file it came from. functions new also stops before writing anything instead of falling back to defaults. secrets set is the one exception
Env applies wherever a key is read	Some readers ignored variables others honoured, e.g. storage and realtime enabled, SUPABASE_API_PORT in functions serve, SUPABASE_API_SCHEMAS in gen types --linked	One behaviour per key, and validation runs on the effective values. Env for a key inside an optional section (webhooks, SMS providers, captcha, SMTP, ...) still applies only when that section exists
Ports	/^\d+$/ in one reader, octal-aware in another	One parser: decimal, 0x, 0o, 0b and _ separators, max 65535. A leading zero (054322) is rejected
SUPABASE_REMOTES_<NAME>_PROJECT_ID	Worked for db commands only	Selects the remote in every command, including secrets set, config diff, config push and storage
Local Docker project id	start and functions fell back to the project ref; the db readers used the folder name	Always the sanitised folder name, never the ref
gen types --local password	Read SUPABASE_DB_PASSWORD	Uses [db].password, like every other --local command
services, functions deploy, functions download, functions serve	Read config.toml only, in places	Read config.json first, like every other command
config push and config diff	Push sent the declared document; diff read the file on its own	Both apply SUPABASE_* and flag overrides and show the same values. Env-sourced rows are labelled, and JSON output carries origin
Default workdir	The walk up from the current directory looked for supabase/config.toml only; some commands then climbed again for config.json	One walk for every command, stopping at the nearest supabase/config.toml or supabase/config.json. A nested config.json project now wins over an outer config.toml one
SUPABASE_SERVICES_HOSTNAME	Read from the project .env by gen types and seed buckets only, ahead of the shell	Read by every local command, shell first, then project .env*. The Docker daemon still comes from the shell environment only
[experimental.inspect.rules]	inspect report accepted a single table and non-string rule fields	Rules must be [[experimental.inspect.rules]] with string fields, as every other command already required
link --password	Listed in help	Hidden, deprecated and ignored with a warning. It never connected to the database

Newly env-overridable keys

Four config keys had no SUPABASE_* override before and now have one:

• auth.sms.otp_expiry (SUPABASE_AUTH_SMS_OTP_EXPIRY)
• auth.sms.otp_length (SUPABASE_AUTH_SMS_OTP_LENGTH)
• db.network_restrictions.allowed_cidrs (SUPABASE_DB_NETWORK_RESTRICTIONS_ALLOWED_CIDRS)
• db.network_restrictions.allowed_cidrs_v6 (SUPABASE_DB_NETWORK_RESTRICTIONS_ALLOWED_CIDRS_V6)

Error codes

• MigrationPasswordFlagsError is now DbPasswordFlagsError.
• Invalid values report CliConfigValueError instead of DbConfigLoadError, SeedConfigLoadError, StatusConfigLoadError or StopConfigLoadError.
• Seeding without consent reports the new SeedConsentRequiredError.

BREAKING CHANGE: Flags and SUPABASE_* environment variables now override config, including a matched [remotes.<name>] block. Every value resolves in one order: flag > shell environment > project env files > config.json/config.toml (a matched remote block over the base) > default. Project env files are .env.<SUPABASE_ENV>.local, .env.local, .env.<SUPABASE_ENV> and .env, in supabase/ and then the project root; SUPABASE_ENV defaults to development.

• If you deploy to a project with a [remotes.*] block, any SUPABASE_* variable in the job or in those files now beats the block. The CLI warns for each value it overrides. Check env | grep ^SUPABASE_ in CI and grep -h ^SUPABASE_ supabase/.env* .env* in the repo, and set SUPABASE_ENV in CI so .env.development doesn't apply.
• supabase config push now pushes those overrides; for example, a SUPABASE_AUTH_SITE_URL in .env.local replaces the value in [remotes.production]. Push labels each env-sourced value, and supabase config diff shows the same values.
• Seeding a project that matches a [remotes.*] block now asks first, unless the block itself sets db.seed.enabled = true. db push --include-seed and db reset --linked exit 1 in CI unless you pass --yes. --include-seed and SUPABASE_DB_SEED_ENABLED=true now override enabled = false in the base [db.seed] too. db push still seeds only with --include-seed.
• --password with --local or --db-url now exits 1 on db push, db pull, db dump, db schema declarative generate, migration list and migration repair. migration squash targets the local database by default, so migration squash -p needs --linked. Put the password in the URL, or set [db].password for the local database.
• In a directory linked to project A, SUPABASE_DB_PASSWORD is no longer sent to another project (--project-ref B). Pass --password, or provide an access token so the CLI can create a temporary login role.
• An invalid value in config or in a SUPABASE_* variable now fails every command that loads project config, including db push, stop and services (for example SUPABASE_STUDIO_PORT=abc). The error names the variable or file and reports CliConfigValueError.
• SUPABASE_EXPERIMENTAL_PGDELTA_ENABLED overrides [experimental.pgdelta].enabled, so false selects migra for the run. Boolean variables, including SUPABASE_EXPERIMENTAL_STACK, accept 1, t, T, true, True, TRUE or 0, f, F, false, False, FALSE and fail on anything else.
• supabase db diff --use-pg-delta=false now turns pg-delta off even when config or env turns it on.
• supabase gen types --local uses [db].password, not SUPABASE_DB_PASSWORD.
• SUPABASE_PROJECT_ID now names local containers even when a remote block matches. Without a project_id in config.toml, local containers and volumes are named after the project folder, not the project ref. Run supabase stop before upgrading, or set project_id.
• Ports with a leading zero (054322) are rejected.
• services and the functions commands read config.json before config.toml.
• Without --workdir, the CLI uses the nearest directory with supabase/config.toml or supabase/config.json, so a nested config.json project now wins over an outer config.toml one.
• inspect report needs [[experimental.inspect.rules]] with string fields; a single [experimental.inspect.rules] table now fails.
• supabase link --password is deprecated and ignored.
• Error codes: MigrationPasswordFlagsError is now DbPasswordFlagsError; invalid values report CliConfigValueError; seeding without consent reports SeedConsentRequiredError.

[jgoux]

Requesting changes for a regression: projects that only have config.json no longer get parent-directory config discovery when the workdir is defaulted. Three smaller notes are inline.

[Coly010]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Verified all seven findings from both independent reviews by reading the cited code and surrounding call paths. All seven are confirmed, with no duplicates. The most serious issue is password disclosure in validation errors; the remaining issues concern configuration consistency, validation, origin metadata, repeated warnings, and documentation.

Findings

Severity	Location	Category	Sources	Claim
🔴 CRITICAL	apps/cli/src/config/cli-config-key-annotations.ts:160	security	codex	Malformed local database passwords are disclosed in validation errors because db.password lacks diagnostic redaction metadata.
🟡 MINOR	apps/cli/src/command-internal/resolved-config-context.ts:42	consistency	claude	Local resolved contexts ignore project-file hostname and Docker settings because they call getHostname without the project environment values they loaded.
🟡 MINOR	apps/cli/src/config/cli-config-values.layer.ts:397	correctness	codex	Environment overrides can expand twice in loaded and materialized config while get(key) expands them once, producing different values for the same key.
🟡 MINOR	apps/cli/src/command-internal/db-config.toml-read.ts:701	validation	codex	The database config reader no longer checks required credentials for enabled custom external providers.
🟡 MINOR	apps/cli/src/config/cli-config-values.layer.ts:445	diagnostics	codex	Deprecation warnings bypass runtime deduplication and repeat when another target is loaded or the caches are invalidated.
⚪ NIT	apps/cli/docs/compute-commands.md:9	documentation	claude	The documented boolean grammar says 'any case', but the parser rejects mixed-case spellings such as tRue.
⚪ NIT	apps/cli/src/config/cli-config-values.layer.ts:422	correctness	claude	materialized.originAt incorrectly attaches the applied remote to untracked values that originated in the base config.

Stats

Claude findings: 3 · Codex findings: 4 · Confirmed: 7 · Refuted: 0 · Uncertain: 0

---

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

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

[Coly010]

/ai-review

[github-actions]

🤖 AI Review

Both independent reviews were available. Code inspection confirmed the credential-withholding defense-in-depth gap and duplicate test fixture, and refuted the secret-recovery claim because valid secret references are expanded before schema failure. Runtime tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/config/cli-config-values.layer.ts:499	security	claude	projectEnvValues retains linked-target credentials even when the loader withholds those credentials from get, envValues, and decoding for a foreign project.
⚪ NIT	apps/cli/src/commands/inspect/report/report.config.unit.test.ts:135	test-quality	codex	The numeric rule-field rejection runs twice with an identical fixture and could be consolidated.

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

• apps/cli/src/commands/secrets/set/set.handler.ts:201 (error-handling): Omitting tolerateInvalid from the fallback load drops valid env-referenced secrets during schema recovery when an unrelated shell override is invalid.
  Refuted: The fallback can fail as described, but valid secret values have already been expanded before recovery. packages/config/src/edge_runtime.ts:33-39 uses secret(), whose definition at packages/config/src/lib/env.ts:35-39 has no deferred-env annotation; the interpolation at :250-260 therefore resolves these references before decoding. set.handler.ts:80-91 preserves those expanded values during recovery, and packages/config/src/lib/resolve.ts:93-94 wraps the resulting literal secrets in Redacted even with an empty lookup. The stated trigger does not discard them.

Stats

Claude findings: 1 · Codex findings: 2 · Confirmed: 2 · Refuted: 1 · Uncertain: 0

---

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

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

[jgoux]

Thanks for the quick turnaround. All four earlier comments are resolved: the config.json ancestor walk, functions new failing before it writes, the exact boolean spellings, and the documented inspect-rules strictness. The other fix commits look good too.

One new P2 remains: an env() reference inside an array loses its environment origin in fileDeclared, so config pull can overwrite it. There is also one small nit, both inline.

[jgoux]

Thanks, both items from the last round are fixed: 663d4a1 keeps array env() references for the decode, so config pull no longer overwrites them, and ce74130 drops the redundant withheldNames filter. Approving.

I also reviewed the overall design against what Effect 4.0.2 provides. The custom parts are justified: Effect's ConfigProvider has no per-value provenance or key listing, no env() interpolation inside documents, and no Go-compatible scalar grammar (bool spellings, base-prefixed and underscored ints, port 0). In 4.0.2, Config.withDefault also turns an invalid value with an absent fallback into the default, which would weaken validation here. The precedence resolver, dotenv/dotenvx handling, document views, and cache wiring fit that gap well. The PR's own Config usage is limited to Config.option(Config.string(...)), so moving to 4.0.2 only needs the constructor renames.

Three P3 edge cases are inline. Two optional, non-blocking design follow-ups:

• readShellEnvironment walks the whole provider tree and needs a segment cap to stay bounded. The registry already knows every env name, so direct lookups for those, plus CliEnvNameSource for the dotenvx key prefix, would cover it with less code.
• The leaf codecs could become Schema transformations (Schema.decodeTo, SchemaGetter.split) shared with flags via Flag.withSchema, giving one parser per type across flags, env, and config. The Go-compatible grammar itself stays custom.

[Coly010]

@jgoux picked up both of your optional follow-ups in 0ed30fd:

1. readShellEnvironment no longer walks the provider. It loads the registry/document names it's given plus the DOTENV_PRIVATE_KEY prefix via CliEnvNameSource, so the segment cap is gone. There's a lookup-only provider test covering registry keys, env() refs, family overrides, remote ids and dotenvx keys.
2. The codecs now decode through one Schema per value type (Schema.decodeTo, SchemaGetter.split) for env and config, with the uint grammar shared with parse-uint. I didn't go as far as Flag.withSchema though: in 4.0.2 it always renders Invalid value for flag --x: "<raw>". Expected: Schema validation failed: …, so it echoes the raw value and we'd lose our redacted messages, and the bool flags need Flag.Boolean for bare toggles anyway. The flag side still goes through the same codec via fromConfig, so it's still one parser per type, just not wired through withSchema. Happy to revisit if you think it's worth it

Also merged next (Effect 4.0.2) in the same push.