docs: update README with browser auth flow and auth command reference

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lohnim

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 <key>`, `--webhook-api-key`, or `ALCHEMY_WEBHOOK_API_KEY`.
 
@@ -165,6 +167,9 @@ Use `alchemy help` or `alchemy help <command>` 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 <id>` | Gets app details | `alchemy apps get <app-id>` |
@@ -231,6 +236,7 @@ Additional env vars:
 
 | Command | Flags |
 |---|---|
+| `auth login` | `--force`, `-y, --yes` |
 | `nfts` | `--limit <n>`, `--page-key <key>` |
 | `nfts metadata` | `--contract <address>` (required), `--token-id <id>` (required) |
 | `tokens` | `--page-key <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