{
  "slug": "wrangler-stores-oauth-credentials-in-the-os-keychain-eae9858ee267",
  "title": "wrangler stores OAuth credentials in the OS keychain",
  "tools": [
    "wrangler"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-07-02T16:33:13.000Z",
  "announced_at": "2026-07-02T16:33:13.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When Wrangler OAuth credentials should be encrypted at rest, run `wrangler login --use-keyring` to store them in an encrypted file with its key in the OS keychain; existing plaintext credentials migrate on first opt-in.",
    "examples": [
      "npx wrangler login --use-keyring",
      "CLOUDFLARE_AUTH_USE_KEYRING=true npx wrangler deploy",
      "npx wrangler login --no-use-keyring"
    ],
    "gotchas": [
      "Version: 4.107.0",
      "Requires Windows lazily installs `@napi-rs/keyring` (~1.9 MB) on first opt-in; Linux requires `secret-tool` from `libsecret-tools`.",
      "--use-keyring: Store OAuth credentials in an encrypted file with the encryption key in the OS keychain; persists the choice.",
      "--no-use-keyring: Opt out; deletes encrypted credentials and the keychain entry.",
      "CLOUDFLARE_AUTH_USE_KEYRING: Set to `true` or `false` to override the saved preference for one invocation.",
      "Prerequisite: macOS uses `/usr/bin/security`; Linux requires `secret-tool` from the `libsecret-tools` package. Windows uses `@napi-rs/keyring`, installed lazily on opt-in; for non-interactive environments, install it ahead of time with `npm install -g @napi-rs/keyring@<version>`.",
      "Prerequisite: Wrangler CLI and an OAuth login flow are required for `wrangler login`; Wrangler recommends installing it locally in the project.",
      "Keyring storage is opt-in; plaintext-file storage remains the default.",
      "Opting out deletes encrypted credentials instead of decrypting them back to disk, so re-authentication is required.",
      "The preference applies to every auth profile; each named profile gets its own encrypted file and key.",
      "Windows errors with instructions in non-interactive/CI contexts when keyring support is first opted into."
    ]
  },
  "why_it_matters": "Opt into encrypted OAuth credential storage when authenticating Wrangler on a development machine or CI runner.",
  "before": "Wrangler stored OAuth access and refresh tokens in a plaintext TOML file by default.",
  "sources": [
    "https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.107.0",
    "https://developers.cloudflare.com/workers/wrangler/commands/general/",
    "https://developers.cloudflare.com/workers/wrangler/install-and-update/"
  ],
  "rank": 0.90023,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v1+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "backfill-20261007",
    "verdict_id": "backfill-20261007:backfill-20261007-8cc335ff8d098b7a-3:gate",
    "evidence_hash": "600392b25956935d6389be815d09ee092c4b7ce2214dda19e3074608718c16ec"
  },
  "review": {
    "draft_hash": "1fc60ee179f9c8598ef0a5956a7e2849feb12d9b78cf5a403cf68eef2a056df0",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "backfill-20261007:gate",
    "reason": "2 of 3 judge runs approved with p_yes >= 0.9 (mean 0.90 >= 0.9; 2 needed) and Jev gave 0.71 (>= 0.6 needed)."
  }
}