!env only resolves from exported variables; .env / .env.local are ignored and the error hides the cause

[benitav]

service.yaml uses uri: !env PS_DATABASE_URI. If the variable is in a .env or .env.local file but not exported, the CLI resolves it to undefined and validate/deploy fail with a message about the URI's protocol, not about the missing variable.

Steps to reproduce:

powersync link cloud --instance-id=<existing instance>

in powersync/service.yaml:

_type: cloud
name: <instance name>
region: <instance region>
replication:
  connections:
    - type: postgresql
      uri: !env PS_DATABASE_URI
client_auth:
  supabase: true

echo 'PS_DATABASE_URI=postgresql://repro:repro@db.example.invalid:5432/postgres' > .env.local
powersync validate --validate-only=connections

You'll get:

[error] unnamed: [PSYNC_S1109] Invalid URI - protocol must be postgresql, got undefined

A misleading error in this case.

Preferred fix:

Either the CLI loads .env.local / .env from the working directory, or it fails with a better error where the missing variable is named.

Context:

The CLI docs and README say "supply the value from an environment variable" and never mention .env files, so technically I guess things work as advertised.

But it confused my agent, and apparently that's because the PowerSync agent skills say "Keep credentials in .env" and lists "PS_DATABASE_URI is in .env" as a readiness gate before powersync validate / deploy. So the agent-skills could also just be updated, but the above fix seems more durable.

🤖 Claude Code helped me narrow down the cause and help me reproduce this.