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.