[wrangler] Document wrangler login --experimental-device#31091
[wrangler] Document wrangler login --experimental-device#31091petebacondarwin wants to merge 2 commits into
wrangler login --experimental-device#31091Conversation
Adds documentation for the new `--experimental-device` flag on `wrangler login`, which uses the OAuth 2.0 Device Authorization Grant (RFC 8628) instead of the default localhost callback flow. Useful in containers, remote SSH sessions, GitHub Codespaces, and any other environment where `localhost:8976` is unreachable from the user's browser. Companion to cloudflare/workers-sdk#14064
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
There was a problem hiding this comment.
Verdict: 2 style guide violations need fixing. Otherwise the PR is accurate and well-structured.
Issues:
- MEDIUM
src/content/docs/workers/wrangler/commands/general.mdx:50— Directional language ("below") violates the style guide. Posted an inline suggestion. - MEDIUM
src/content/docs/workers/wrangler/commands/general.mdx:123— Directional language ("previous sections") violates the style guide. Posted an inline suggestion.
Summary: Documents the new --experimental-device flag for wrangler login, which enables the OAuth 2.0 Device Authorization Grant for environments where the localhost callback is unreachable. Adds the flag to the options list and a new subsection explaining the flow, QR code output, and interaction with --browser=false. Added product:workers and documentation labels.
| - Defaults to `8976`. Sets the port where Wrangler should listen for the OAuth callback. | ||
| - Defaults to `8976`. Sets the port where Wrangler should listen for the OAuth callback. Ignored when `--experimental-device` is set. | ||
| - `--experimental-device` <Type text="boolean" /> <MetaInfo text="optional" /> | ||
| - Defaults to `false`. Use the OAuth 2.0 Device Authorization Grant ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) instead of the default localhost callback flow. See [Use `wrangler login` without a local callback server](#use-wrangler-login-without-a-local-callback-server) below. |
There was a problem hiding this comment.
Replace directional language per style guide:
| - Defaults to `false`. Use the OAuth 2.0 Device Authorization Grant ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) instead of the default localhost callback flow. See [Use `wrangler login` without a local callback server](#use-wrangler-login-without-a-local-callback-server) below. | |
| - Defaults to `false`. Use the OAuth 2.0 Device Authorization Grant ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) instead of the default localhost callback flow. Refer to [Use `wrangler login` without a local callback server](#use-wrangler-login-without-a-local-callback-server). |
| The `--experimental-device` flag is experimental. The flag name, output, and exact behavior may change in future releases. | ||
| ::: | ||
|
|
||
| The default `wrangler login` flow needs your browser to be able to reach a temporary local server on `localhost:8976`. In some environments — remote SSH sessions, containers without forwarded ports, GitHub Codespaces, or otherwise restricted networks — that callback URL is unreachable from the browser, and the workarounds in the previous sections may be difficult to set up. |
There was a problem hiding this comment.
Avoid directional language ("previous sections"). Reference by topic instead:
| The default `wrangler login` flow needs your browser to be able to reach a temporary local server on `localhost:8976`. In some environments — remote SSH sessions, containers without forwarded ports, GitHub Codespaces, or otherwise restricted networks — that callback URL is unreachable from the browser, and the workarounds in the previous sections may be difficult to set up. | |
| The default `wrangler login` flow needs your browser to be able to reach a temporary local server on `localhost:8976`. In some environments — remote SSH sessions, containers without forwarded ports, GitHub Codespaces, or otherwise restricted networks — that callback URL is unreachable from the browser, and setting up the workarounds for remote machines and containers may be difficult. |
|
Verdict: Posted 2 inline suggestions. Otherwise the PR is accurate and well-structured. Issues:
Labels applied: What the PR changes: Documents the new |
|
Preview URL: https://7bce811f.preview.developers.cloudflare.com Files with changes (up to 15) |
Replaces directional language ("below", "previous sections") with
topic-referenced wording per the Cloudflare docs style guide.
- Line 50: 'See ... below' \u2192 'Refer to ...'
- Line 123: 'workarounds in the previous sections' \u2192 'workarounds for
remote machines and containers'
No semantic change.
3 participants
Summary
Documents the new experimental
wrangler login --experimental-deviceflag, which adds support for the OAuth 2.0 Device Authorization Grant to Wrangler.This flow is useful in environments where the default localhost callback flow is impractical:
localhost:8976is unreachable from the browser.It does not start a local callback server. Instead, Wrangler prints a verification URL and short user code, opens the URL in the user's default browser, prints a QR code of the URL, and polls Cloudflare for an access token until the user approves.
Companion to cloudflare/workers-sdk#14064.
This is a draft PR — the underlying wrangler PR is also draft and depends on server-side rollout of OAuth Device Authorization Grant in Hydra (tracked in AUTHN-168 and AUTHN-173). I'll un-draft this once the wrangler-side PR is ready to release.
Documentation checklist