Skip to content

docs(cli): document device-code login for headless environments #1429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SahilAujla merged 3 commits into from
Jul 10, 2026
Merged

docs(cli): document device-code login for headless environments #1429

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6e956f2
docs(cli): document device-code login for headless environments
SahilAujla Jul 6, 2026
0002efb
docs(cli): plain punctuation in the headless auth paragraph
SahilAujla Jul 6, 2026
9e48ed5
docs(cli): list the auto-detected environments for device-code login
SahilAujla Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions content/tutorials/build-with-ai/alchemy-cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
SahilAujla marked this conversation as resolved.
Outdated

### Selecting an app

To change the selected app later, list your apps and select one:

```bash
Expand Down Expand Up @@ -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 |
Expand Down
Loading