{
  "slug": "wrangler-dotenv-secrets-file-expands-variable-references-0ec2af323ecb",
  "title": "wrangler dotenv --secrets-file expands variable references",
  "tools": [
    "wrangler"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-10-26T14:32:42.000Z",
  "announced_at": "2026-10-26T14:32:42.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When uploading secrets with Wrangler, use `--secrets-file <file>` with `deploy` or `versions upload` to provide a JSON or dotenv file. The docs do not show this flag for `preview` or document dotenv variable expansion, so those details are not included as verified usage.",
    "examples": [
      "npx wrangler deploy --secrets-file <dotenv-or-json-file>",
      "npx wrangler versions upload --secrets-file <dotenv-or-json-file>"
    ],
    "gotchas": [
      "Version: 4.153.0",
      "--secrets-file <file>: Optional path to a JSON or `.env` file containing secrets to upload; existing secrets omitted from the file are preserved. The flag takes a file path when used.",
      "Unset references become an empty string; for example, `PASSWORD=pa$word` becomes `pa` when `word` is unset.",
      "Process environment values override matching file keys, including explicitly empty values.",
      "Dotenv secrets files can read and upload any process environment value, so their contents should not be modifiable by untrusted contributors in CI.",
      "JSON secrets input and bulk-secret commands, including piped stdin, retain literal parsing."
    ]
  },
  "why_it_matters": "When deploying, uploading a version, or previewing with a dotenv secrets file, preserve and manage variable references and their process environment values.",
  "before": "Provide dotenv input through `--secrets-file` with values parsed literally, without expanding `$VAR` or `${VAR}` references.",
  "sources": [
    "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.153.0",
    "https://developers.cloudflare.com/workers/configuration/secrets/",
    "https://developers.cloudflare.com/workers/wrangler/commands/workers/"
  ],
  "rank": 0.9504,
  "review_state": "approved",
  "provenance": {
    "run_id": "daily-20261027-04",
    "verdict_id": "daily-20261027-04:daily-20261027-04-336141da1cf5c4df-1:gate",
    "evidence_hash": "63ea01483527eea653c6543401fd003fc0ea03c63aae82f263391b02cad64fb6"
  }
}