From c65f4c441556a60ec37e2485237097f0078821ac Mon Sep 17 00:00:00 2001 From: "chris.lee" Date: Wed, 1 Apr 2026 11:40:36 -0400 Subject: [PATCH 1/3] chore: add changeset for auth improvements Co-Authored-By: Claude Opus 4.6 (1M context) --- .changeset/auth-improvements.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/auth-improvements.md diff --git a/.changeset/auth-improvements.md b/.changeset/auth-improvements.md new file mode 100644 index 0000000..230fe5e --- /dev/null +++ b/.changeset/auth-improvements.md @@ -0,0 +1,5 @@ +--- +"@alchemy/cli": patch +--- + +Improve auth flow: browser-only onboarding, auto-prompt app selection when API key missing, searchable app list, updated auth success page styling, and fix config list to show auth/webhook fields From 3c611da0f0163cabee79319a1b9f00e6b51e2550 Mon Sep 17 00:00:00 2001 From: "chris.lee" Date: Wed, 1 Apr 2026 13:19:34 -0400 Subject: [PATCH 2/3] docs: update README with browser auth flow and auth command reference Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 54 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index bc5e131..e9068f2 100644 --- a/README.md +++ b/README.md @@ -39,21 +39,23 @@ alchemy completions fish > ~/.config/fish/completions/alchemy.fish ### Authentication Quick Start -Authentication is required before making requests. Configure auth first, then run commands. - -If you are using the CLI as a human in an interactive terminal, the easiest path is: +Authentication is required before making requests. The recommended path is browser login: ```bash -alchemy +alchemy auth ``` -Then follow the setup flow in the terminal UI to configure auth. +This opens a browser to link your Alchemy account, then prompts you to select an app. The selected app's API key is saved to your config automatically. Pass `-y` to skip the confirmation prompt. + +If you run `alchemy` with no command and no auth configured, the CLI will guide you through browser login automatically. + +If you have an auth token but haven't selected an app yet, the CLI will prompt you to pick one before running any command that requires an API key. Teams with many apps can type to search by name. -Know which auth method does what: +Other auth methods are available for specific use cases: -- **API key** - direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`) -- **Access key** - Admin/API app management; app setup/selection can also provide API key auth for blockchain queries -- **x402 wallet auth** - wallet-authenticated, pay-per-request model for supported blockchain queries +- **API key** — direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`) +- **Access key** — Admin API app management; app setup/selection can also provide API key auth for blockchain queries +- **x402 wallet auth** — wallet-authenticated, pay-per-request model for supported blockchain queries If you use Notify webhooks, add webhook auth on top via `alchemy config set webhook-api-key `, `--webhook-api-key`, or `ALCHEMY_WEBHOOK_API_KEY`. @@ -165,6 +167,9 @@ Use `alchemy help` or `alchemy help ` for generated command help. | Command | What it does | Example | |---|---|---| | `(no command)` | Starts interactive REPL mode (TTY only) | `alchemy` | +| `auth` (`auth login`) | Log in via browser (PKCE) | `alchemy auth` | +| `auth status` | Show current authentication status | `alchemy auth status` | +| `auth logout` | Clear saved authentication token | `alchemy auth logout` | | `apps list` | Lists apps (supports pagination/filtering) | `alchemy apps list --all` | | `apps chains` | Lists Admin API chain identifiers (e.g. `ETH_MAINNET`) | `alchemy apps chains` | | `apps get ` | Gets app details | `alchemy apps get ` | @@ -231,6 +236,7 @@ Additional env vars: | Command | Flags | |---|---| +| `auth login` | `--force`, `-y, --yes` | | `nfts` | `--limit `, `--page-key ` | | `nfts metadata` | `--contract
` (required), `--token-id ` (required) | | `tokens` | `--page-key ` | @@ -258,17 +264,39 @@ Additional env vars: ## Authentication Reference -The CLI supports three auth inputs: +The CLI supports four auth methods: -- API key for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`) -- Access key for Admin API operations (`apps`, `chains`, configured network lookups`) and app setup/selection, which can also supply the API key used by blockchain query commands -- x402 wallet key for wallet-authenticated blockchain queries in a pay-per-request model +- **Browser login** (recommended) — log in via `alchemy auth`, then select an app to automatically configure your API key +- **API key** — direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`) +- **Access key** — Admin API operations (`apps`, `chains`, configured network lookups`) and app setup/selection, which can also supply the API key used by blockchain query commands +- **x402 wallet key** — wallet-authenticated blockchain queries in a pay-per-request model Notify/webhook commands use a webhook API key with resolution order: `--webhook-api-key` -> `ALCHEMY_WEBHOOK_API_KEY` -> `ALCHEMY_NOTIFY_AUTH_TOKEN` -> config `webhook-api-key` -> configured app webhook key. Get API/access keys at [alchemy.com](https://dashboard.alchemy.com/). +#### Browser login (recommended) + +```bash +# Interactive login — opens browser to link your Alchemy account +alchemy auth + +# Skip the confirmation prompt +alchemy auth -y + +# Force re-authentication +alchemy auth login --force + +# Check auth status +alchemy auth status + +# Log out +alchemy auth logout +``` + +After login, the CLI prompts you to select an app. The app's API key is saved to config and used for all subsequent commands. If you skip app selection during login, the CLI will prompt you to pick one before running any command that needs an API key. + #### API key ```bash From 959f065265240378ae64a0c3b6f5761aa89c9007 Mon Sep 17 00:00:00 2001 From: "chris.lee" Date: Wed, 1 Apr 2026 13:20:55 -0400 Subject: [PATCH 3/3] docs: simplify README auth section to browser login only Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 81 ++----------------------------------------------------- 1 file changed, 2 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index e9068f2..5324abe 100644 --- a/README.md +++ b/README.md @@ -51,16 +51,8 @@ If you run `alchemy` with no command and no auth configured, the CLI will guide If you have an auth token but haven't selected an app yet, the CLI will prompt you to pick one before running any command that requires an API key. Teams with many apps can type to search by name. -Other auth methods are available for specific use cases: - -- **API key** — direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`) -- **Access key** — Admin API app management; app setup/selection can also provide API key auth for blockchain queries -- **x402 wallet auth** — wallet-authenticated, pay-per-request model for supported blockchain queries - If you use Notify webhooks, add webhook auth on top via `alchemy config set webhook-api-key `, `--webhook-api-key`, or `ALCHEMY_WEBHOOK_API_KEY`. -For setup commands, env vars, and resolution order, see [Authentication Reference](#authentication-reference). - ### Usage By Workflow After auth is configured, use the CLI differently depending on who is driving it: @@ -264,20 +256,6 @@ Additional env vars: ## Authentication Reference -The CLI supports four auth methods: - -- **Browser login** (recommended) — log in via `alchemy auth`, then select an app to automatically configure your API key -- **API key** — direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`) -- **Access key** — Admin API operations (`apps`, `chains`, configured network lookups`) and app setup/selection, which can also supply the API key used by blockchain query commands -- **x402 wallet key** — wallet-authenticated blockchain queries in a pay-per-request model - -Notify/webhook commands use a webhook API key with resolution order: -`--webhook-api-key` -> `ALCHEMY_WEBHOOK_API_KEY` -> `ALCHEMY_NOTIFY_AUTH_TOKEN` -> config `webhook-api-key` -> configured app webhook key. - -Get API/access keys at [alchemy.com](https://dashboard.alchemy.com/). - -#### Browser login (recommended) - ```bash # Interactive login — opens browser to link your Alchemy account alchemy auth @@ -297,63 +275,8 @@ alchemy auth logout After login, the CLI prompts you to select an app. The app's API key is saved to config and used for all subsequent commands. If you skip app selection during login, the CLI will prompt you to pick one before running any command that needs an API key. -#### API key - -```bash -# Config -alchemy config set api-key - -# Environment variable -export ALCHEMY_API_KEY= - -# Per-command override -alchemy balance 0x... --api-key -``` - -Resolution order: `--api-key` -> `ALCHEMY_API_KEY` -> config file -> configured app API key. - -#### Access key - -```bash -# Config (in TTY, this may trigger app setup flow) -alchemy config set access-key - -# Environment variable -export ALCHEMY_ACCESS_KEY= - -# Per-command override -alchemy apps list --access-key -``` - -Resolution order: `--access-key` -> `ALCHEMY_ACCESS_KEY` -> config file. - -#### x402 wallet auth - -x402 is a wallet-authenticated, pay-per-request usage model for supported blockchain queries. -The CLI can generate or import the wallet key used for these requests. - -```bash -# Generate/import a wallet managed by CLI -alchemy wallet generate -# or -alchemy wallet import ./private-key.txt - -# Use x402 per command -alchemy balance 0x... --x402 - -# Or enable by default -alchemy config set x402 true -``` - -Generated/imported wallets are stored as unique key files under `~/.config/alchemy/wallet-keys/` so creating another wallet does not overwrite prior private keys. - -You can also provide wallet key directly: - -```bash -export ALCHEMY_WALLET_KEY=0x... -``` - -Wallet key resolution order: `--wallet-key-file` -> `ALCHEMY_WALLET_KEY` -> `wallet-key-file` in config. +Notify/webhook commands use a webhook API key with resolution order: +`--webhook-api-key` -> `ALCHEMY_WEBHOOK_API_KEY` -> `ALCHEMY_NOTIFY_AUTH_TOKEN` -> config `webhook-api-key` -> configured app webhook key. ## REPL Mode