[wrangler] Document opt-in OS keychain credential storage#31211
[wrangler] Document opt-in OS keychain credential storage#31211petebacondarwin wants to merge 1 commit into
Conversation
petebacondarwin
requested review from
a team,
MattieTK,
irvinebroque and
vy-ton
as code owners
Review❌ Review failed for commit |
github-actions
Bot
added
product:workers
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| - **Linux** uses [libsecret](https://wiki.gnome.org/Projects/Libsecret) via the `secret-tool` CLI from the `libsecret-tools` package. | ||
| - **Windows** uses Credential Manager via [`@napi-rs/keyring`](https://www.npmjs.com/package/@napi-rs/keyring), installed on-demand the first time you opt in. | ||
|
|
||
| Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for the full details, including the migration behavior on opt-in/opt-out and the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable. |
There was a problem hiding this comment.
🔴 Broken link: anchor targets commands index page instead of commands/general page
The link /workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain resolves to src/content/docs/workers/wrangler/commands/index.mdx, which is a navigation page containing only #workers-commands, #all-commands, and #how-to-run-wrangler-commands anchors. The #storing-oauth-credentials-in-the-os-keychain anchor exists in src/content/docs/workers/wrangler/commands/general.mdx:116, so the correct path is /workers/wrangler/commands/general/#storing-oauth-credentials-in-the-os-keychain. Other changelog entries in the repo correctly use the /workers/wrangler/commands/general/#... pattern for anchors in general.mdx.
| Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for the full details, including the migration behavior on opt-in/opt-out and the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable. | |
| Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/general/#storing-oauth-credentials-in-the-os-keychain) for the full details, including the migration behavior on opt-in/opt-out and the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable. |
Was this helpful? React with 👍 or 👎 to provide feedback.
| - The Client Secret of a [Cloudflare Access Service Token](/cloudflare-one/access-controls/service-credentials/service-tokens/), used together with `CLOUDFLARE_ACCESS_CLIENT_ID` to authenticate with Access-protected domains in non-interactive environments. For the full Access policy and service token setup, refer to [Connect to Access-protected Workers](/workers/development-testing/#connect-to-access-protected-workers). | ||
|
|
||
| - `CLOUDFLARE_AUTH_USE_KEYRING` <Type text="boolean" /> <MetaInfo text="optional" /> | ||
| - Options for this are `true` and `false`. Defaults to unset. Overrides the persistent preference set by `wrangler login --use-keyring` / `--no-use-keyring` for a single invocation. When `true`, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When `false`, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled. Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for details. |
There was a problem hiding this comment.
🔴 Broken link: anchor targets commands index page instead of commands/general page
Same issue as in the changelog — the link /workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain points to the commands index page (src/content/docs/workers/wrangler/commands/index.mdx), which does not contain the target anchor. The anchor exists in src/content/docs/workers/wrangler/commands/general.mdx:116. The correct path is /workers/wrangler/commands/general/#storing-oauth-credentials-in-the-os-keychain.
| - Options for this are `true` and `false`. Defaults to unset. Overrides the persistent preference set by `wrangler login --use-keyring` / `--no-use-keyring` for a single invocation. When `true`, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When `false`, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled. Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for details. | |
| - Options for this are `true` and `false`. Defaults to unset. Overrides the persistent preference set by `wrangler login --use-keyring` / `--no-use-keyring` for a single invocation. When `true`, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When `false`, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled. Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/general/#storing-oauth-credentials-in-the-os-keychain) for details. |
Was this helpful? React with 👍 or 👎 to provide feedback.
ask-bonk
Bot
added
documentation
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
| date: 2026-06-03 | ||
| --- | ||
|
|
||
| [Wrangler](/workers/wrangler/) can now store the OAuth credentials returned by `wrangler login` in an [AES-256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode)-encrypted file, with the encryption key held in your operating system's keychain. The default behavior is unchanged — credentials still live in a plaintext TOML file unless you opt in. |
There was a problem hiding this comment.
Avoid the possessive for an inanimate object per the style guide:
| [Wrangler](/workers/wrangler/) can now store the OAuth credentials returned by `wrangler login` in an [AES-256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode)-encrypted file, with the encryption key held in your operating system's keychain. The default behavior is unchanged — credentials still live in a plaintext TOML file unless you opt in. | |
| [Wrangler](/workers/wrangler/) can now store the OAuth credentials returned by `wrangler login` in an [AES-256-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode)-encrypted file, with the encryption key held in your operating system keychain. The default behavior is unchanged — credentials still live in a plaintext TOML file unless you opt in. |
| - **Linux** uses [libsecret](https://wiki.gnome.org/Projects/Libsecret) via the `secret-tool` CLI from the `libsecret-tools` package. | ||
| - **Windows** uses Credential Manager via [`@napi-rs/keyring`](https://www.npmjs.com/package/@napi-rs/keyring), installed on-demand the first time you opt in. | ||
|
|
||
| Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for the full details, including the migration behavior on opt-in/opt-out and the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable. |
There was a problem hiding this comment.
This links to the navigation index page, not the general commands page:
| Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for the full details, including the migration behavior on opt-in/opt-out and the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable. | |
| Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/general/#storing-oauth-credentials-in-the-os-keychain) for the full details, including the migration behavior on opt-in/opt-out and the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable. |
| - `--callback-port` <Type text="string" /> <MetaInfo text="optional" /> | ||
| - Defaults to `8976`. Sets the port where Wrangler should listen for the OAuth callback. | ||
| - `--use-keyring` <Type text="boolean" /> <MetaInfo text="optional" /> | ||
| - Store the OAuth credentials in your operating system's keychain instead of the default plaintext TOML file. Refer to [Storing OAuth credentials in the OS keychain](#storing-oauth-credentials-in-the-os-keychain) for details. Use `--no-use-keyring` to opt back out. The choice is persisted across Wrangler invocations. |
There was a problem hiding this comment.
Use third-person verb form for consistency with other flags, and avoid the possessive for an inanimate object:
| - Store the OAuth credentials in your operating system's keychain instead of the default plaintext TOML file. Refer to [Storing OAuth credentials in the OS keychain](#storing-oauth-credentials-in-the-os-keychain) for details. Use `--no-use-keyring` to opt back out. The choice is persisted across Wrangler invocations. | |
| - Stores the OAuth credentials in your operating system keychain instead of the default plaintext TOML file. Refer to [Storing OAuth credentials in the OS keychain](#storing-oauth-credentials-in-the-os-keychain) for details. Use `--no-use-keyring` to opt back out. The choice is persisted across Wrangler invocations. |
|
|
||
| ### Storing OAuth credentials in the OS keychain | ||
|
|
||
| By default, Wrangler stores the OAuth access token and refresh token returned by `wrangler login` in a plaintext TOML file under the global Wrangler config directory (typically `~/.config/.wrangler/config/default.toml`). Pass `--use-keyring` to opt in to a more secure storage path that uses your operating system's keychain: |
There was a problem hiding this comment.
Avoid the possessive for an inanimate object:
| By default, Wrangler stores the OAuth access token and refresh token returned by `wrangler login` in a plaintext TOML file under the global Wrangler config directory (typically `~/.config/.wrangler/config/default.toml`). Pass `--use-keyring` to opt in to a more secure storage path that uses your operating system's keychain: | |
| By default, Wrangler stores the OAuth access token and refresh token returned by `wrangler login` in a plaintext TOML file under the global Wrangler config directory (typically `~/.config/.wrangler/config/default.toml`). Pass `--use-keyring` to opt in to a more secure storage path that uses your operating system keychain: |
| - The Client Secret of a [Cloudflare Access Service Token](/cloudflare-one/access-controls/service-credentials/service-tokens/), used together with `CLOUDFLARE_ACCESS_CLIENT_ID` to authenticate with Access-protected domains in non-interactive environments. For the full Access policy and service token setup, refer to [Connect to Access-protected Workers](/workers/development-testing/#connect-to-access-protected-workers). | ||
|
|
||
| - `CLOUDFLARE_AUTH_USE_KEYRING` <Type text="boolean" /> <MetaInfo text="optional" /> | ||
| - Options for this are `true` and `false`. Defaults to unset. Overrides the persistent preference set by `wrangler login --use-keyring` / `--no-use-keyring` for a single invocation. When `true`, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When `false`, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled. Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for details. |
There was a problem hiding this comment.
This links to the navigation index page, not the general commands page:
| - Options for this are `true` and `false`. Defaults to unset. Overrides the persistent preference set by `wrangler login --use-keyring` / `--no-use-keyring` for a single invocation. When `true`, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When `false`, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled. Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/#storing-oauth-credentials-in-the-os-keychain) for details. | |
| - Options for this are `true` and `false`. Defaults to unset. Overrides the persistent preference set by `wrangler login --use-keyring` / `--no-use-keyring` for a single invocation. When `true`, Wrangler stores OAuth credentials in an encrypted file with the encryption key held in the OS keychain, and exits with an error if the keychain backend is unavailable. When `false`, Wrangler uses the legacy plaintext TOML file even if the persistent preference is enabled. Refer to [Storing OAuth credentials in the OS keychain](/workers/wrangler/commands/general/#storing-oauth-credentials-in-the-os-keychain) for details. |
|
Review posted. Applied labels: 5 inline suggestions posted. Issues to address:
No pre-existing issues in the surrounding files were flagged. |
4 participants
Summary
Documents the opt-in OS keychain credential storage feature added to Wrangler in
cloudflare/workers-sdk#14156.Changes:
src/content/docs/workers/wrangler/commands/general.mdx--use-keyring/--no-use-keyringto thewrangler loginflags.security, Linuxsecret-tool, Windows@napi-rs/keyring),wrangler whoamireporting, opt-out semantics (deletes the encrypted file — does not decrypt onto disk), theCLOUDFLARE_AUTH_USE_KEYRINGper-process override, and compatibility with API-token auth.wrangler logoutdescription to note keychain cleanup.src/content/docs/workers/wrangler/system-environment-variables.mdxCLOUDFLARE_AUTH_USE_KEYRINGto the supported environment variables list.src/content/changelog/workers/2026-06-03-wrangler-keyring-credential-storage.mdxCompanion PRs
cloudflare/workers-sdk#14156Documentation checklist
2026-06-03-wrangler-keyring-credential-storage.mdx.