From 6e956f2967387feae2317b7ae22cc5abb1867739 Mon Sep 17 00:00:00 2001 From: Sahil Aujla Date: Mon, 6 Jul 2026 14:20:12 -0400 Subject: [PATCH 1/3] docs(cli): document device-code login for headless environments @alchemy/cli 0.18.0 added an OAuth 2.0 Device Authorization Grant (RFC 8628) so alchemy auth works in Codespaces, sandboxes, SSH, and CI where the browser cannot reach the CLI's localhost callback. Add a Headless and remote environments subsection to the Authenticate section and a command-reference row for alchemy auth login --device-code. Co-Authored-By: Claude Fable 5 --- content/tutorials/build-with-ai/alchemy-cli.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/content/tutorials/build-with-ai/alchemy-cli.mdx b/content/tutorials/build-with-ai/alchemy-cli.mdx index da2346553..b68438c16 100644 --- a/content/tutorials/build-with-ai/alchemy-cli.mdx +++ b/content/tutorials/build-with-ai/alchemy-cli.mdx @@ -32,6 +32,18 @@ Sign in via browser. The CLI saves a token and prompts you to pick an app, then alchemy auth ``` +### Headless and remote environments + +If the CLI runs where a browser can't reach it — GitHub Codespaces, SSH sessions, sandboxes, CI — use the device authorization flow. The CLI prints a short code and a verification link; open the link in a browser on any device, check the code matches the one in your terminal, and approve. + +```bash +alchemy auth login --device-code +``` + +Plain `alchemy auth` also auto-detects remote and non-interactive environments and switches to this flow on its own, so remote sessions usually don't need the flag. + +### Selecting an app + To change the selected app later, list your apps and select one: ```bash @@ -318,6 +330,7 @@ Filters are optional and combined with AND. `--group-by` accepts at most one dim | Command | Description | |---|---| | `alchemy auth` | Sign in via browser. Use `alchemy auth login --force` to re-authenticate and `-y` to skip the confirmation prompt. | +| `alchemy auth login --device-code` | Sign in from headless or remote environments (Codespaces, sandboxes, SSH, CI) by approving a short code in a browser on any device. Auto-detected for remote and non-interactive sessions. | | `alchemy auth status` | Show whether you're signed in | | `alchemy auth logout` | Clear the saved authentication token | | `alchemy doctor` | Run setup checks and print remediation commands | From 0002efb20466d67f6a19bb2cfd08936f1ca980e5 Mon Sep 17 00:00:00 2001 From: Sahil Aujla Date: Mon, 6 Jul 2026 14:27:12 -0400 Subject: [PATCH 2/3] docs(cli): plain punctuation in the headless auth paragraph Co-Authored-By: Claude Fable 5 --- content/tutorials/build-with-ai/alchemy-cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/tutorials/build-with-ai/alchemy-cli.mdx b/content/tutorials/build-with-ai/alchemy-cli.mdx index b68438c16..c6a91e678 100644 --- a/content/tutorials/build-with-ai/alchemy-cli.mdx +++ b/content/tutorials/build-with-ai/alchemy-cli.mdx @@ -34,7 +34,7 @@ alchemy auth ### Headless and remote environments -If the CLI runs where a browser can't reach it — GitHub Codespaces, SSH sessions, sandboxes, CI — use the device authorization flow. The CLI prints a short code and a verification link; open the link in a browser on any device, check the code matches the one in your terminal, and approve. +If the CLI runs somewhere a browser can't reach it, like GitHub Codespaces, SSH sessions, sandboxes, or CI, use the device authorization flow. The CLI prints a short code and a verification link. Open the link in a browser on any device, check the code matches the one in your terminal, and approve. ```bash alchemy auth login --device-code From 9e48ed52615d1d13be846f7e0bcd43d4bc87961b Mon Sep 17 00:00:00 2001 From: Sahil Aujla Date: Mon, 6 Jul 2026 15:04:36 -0400 Subject: [PATCH 3/3] docs(cli): list the auto-detected environments for device-code login Enumerate exactly which environments switch to the device flow on their own (Codespaces, Gitpod, Replit, Cloud Shell, Coder, SSH, and non-interactive sessions) and make explicit that the flag works everywhere, with the browser-login timeout pointing at it as the fallback. Co-Authored-By: Claude Fable 5 --- content/tutorials/build-with-ai/alchemy-cli.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/content/tutorials/build-with-ai/alchemy-cli.mdx b/content/tutorials/build-with-ai/alchemy-cli.mdx index c6a91e678..bd9805a8d 100644 --- a/content/tutorials/build-with-ai/alchemy-cli.mdx +++ b/content/tutorials/build-with-ai/alchemy-cli.mdx @@ -34,13 +34,19 @@ alchemy auth ### Headless and remote environments -If the CLI runs somewhere a browser can't reach it, like GitHub Codespaces, SSH sessions, sandboxes, or CI, use the device authorization flow. The CLI prints a short code and a verification link. Open the link in a browser on any device, check the code matches the one in your terminal, and approve. +If the CLI runs somewhere a browser can't reach it, use the device authorization flow. The CLI prints a short code and a verification link. Open the link in a browser on any device, check the code matches the one in your terminal, and approve. ```bash alchemy auth login --device-code ``` -Plain `alchemy auth` also auto-detects remote and non-interactive environments and switches to this flow on its own, so remote sessions usually don't need the flag. +The flag works in every environment. Plain `alchemy auth` also switches to this flow on its own when it detects one of the following, so these don't need the flag: + +* GitHub Codespaces, Gitpod, Replit, Google Cloud Shell, and Coder workspaces +* SSH sessions +* Non-interactive sessions like CI and piped output, where the browser flow can't prompt + +If auto-detection misses your environment, the browser login times out after two minutes and its error points you to the same command. ### Selecting an app