Secrets

Declaring secrets

export default defineConfig({
  secrets: {
    "apps/api": [
      "AUTH_SECRET",
      "API_KEY",
      { name: "STRIPE_KEY", ref: true }, // managed externally — see below
    ],
    "apps/worker": ["API_KEY"],
  },
});

External references with { name, ref: true }

A { name, ref: true } entry tells wrangler-deploy that the secret is already in Cloudflare via wrangler secret put (or another tool) and that wrangler-deploy should not push it on deploy. Useful when:

• Your secrets pipeline is owned by a different team or system.
• You don’t want to round-trip large secrets through CI on every deploy.
• You want one declaration for “this binding exists” without centralising the value.

Behaviour:

| Tool | Plain entry | ref: true entry | |---------------------------|------------------------|-------------------------------------| | wd secrets | + NAME: set / x: missing | → NAME: ref (external) when present, x: missing if not | | wd secrets set | Prompts for value | Skipped | | wd secrets sync | Pushes if value in env | Skipped (logged as ref) | | wd deploy gating | Fails if missing | Fails only if not seen by wd secrets yet |

Refs are observed by wd secrets (which calls wrangler secret list once per worker). After they’re observed they pass deploy validation.

Checking

wd secrets --stage staging

apps/api:
  + AUTH_SECRET: set
  x API_KEY: missing

1 missing. Run "wd secrets set --stage staging" to fix

Setting interactively

wd secrets set --stage staging
# Prompts for each missing secret

Syncing from env file

wd secrets sync --to pr-123 --from-env-file .dev.vars

Reads the file, matches keys to declared secrets, sets each via wrangler secret put.

Deploy gating

Deploy blocks if any declared secret is missing:

Blocked: 1 missing secret(s):
  x apps/api/API_KEY

Run "wd secrets set --stage staging"

State encryption

By default, state includes sensitive values like Hyperdrive origins and stored secrets in plain text. You can encrypt these at rest using AES-256-GCM with a password you provide:

$ wd apply --stage staging --encrypt
Enter encryption password: ********

Or set it in your .wdrc:

// .wdrc or .wdrc.json
{
  "stage": "staging",
  "encryptPassword": "your-password-here"
}

How it works

• On apply, the password encrypts HyperdriveOutput.origin and values in storedSecrets before writing state to disk
• On commands that read state (deploy, status, etc.), the password decrypts those fields
• If the password is wrong or omitted, encrypted fields are left as-is — the command runs but can’t access those values

State files are typically .wrangler-deploy/<stage>/state.json. With encryption enabled, they look like:

{
  "resources": {
    "payments-db": {
      "output": {
        "origin": "v1:AQAAAA...==:AAAAAAAA:BBBBBBBB:CCCCCCCC:encrypted-base64"
      }
    }
  },
  "storedSecrets": {
    "apps/api": {
      "AUTH_SECRET": "v1:AAAA...:BBBB...:CCCC...:DDDD..."
    }
  }
}

The v1: prefix marks encrypted fields. Decrypting restores the original values for runtime use.