[wrangler] Document opt-in OS keychain credential storage#31211
Open
petebacondarwin wants to merge 2 commits into
Open
[wrangler] Document opt-in OS keychain credential storage#31211petebacondarwin wants to merge 2 commits into
petebacondarwin wants to merge 2 commits into
Conversation
Contributor
Review
Warnings (2)
Suggestions (7)
CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
5 tasks
| - **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. |
Contributor
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.
Suggested change
| 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. |
Contributor
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.
Suggested change
| - 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.
| 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. |
Contributor
There was a problem hiding this comment.
Avoid the possessive for an inanimate object per the style guide:
Suggested change
| [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. |
Contributor
There was a problem hiding this comment.
This links to the navigation index page, not the general commands page:
Suggested change
| 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. |
Contributor
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:
Suggested change
| - 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: |
Contributor
There was a problem hiding this comment.
Avoid the possessive for an inanimate object:
Suggested change
| 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. |
Contributor
There was a problem hiding this comment.
This links to the navigation index page, not the general commands page:
Suggested change
| - 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. |
Contributor
|
Review posted. Applied labels: 5 inline suggestions posted. Issues to address:
No pre-existing issues in the surrounding files were flagged. |
Contributor
Contributor
|
Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant). |
ad8ba94 to
1b1c85a
Compare
- Fix broken anchor links: point to commands/general/ instead of commands/ - Use third-person 'Stores' for --use-keyring to match other flag descriptions - Drop possessive on 'operating system keychain' per style guide
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.