@alchemy/cli 0.5.2 → 0.6.1

package/README.md

@@ -109,7 +109,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 
 | Command | What it does | Example |
 |---|---|---|
-| `tokens [address]` | Lists ERC-20 balances for an address | `alchemy tokens 0x...` |
+| `tokens balances [address]` | Lists ERC-20 balances for an address | `alchemy tokens balances 0x...` |
 | `tokens metadata <contract>` | Gets ERC-20 metadata | `alchemy tokens metadata 0x...` |
 | `tokens allowance --owner --spender --contract` | Gets ERC-20 allowance | `alchemy tokens allowance --owner 0x... --spender 0x... --contract 0x...` |
 | `nfts [address]` | Lists NFTs owned by an address | `alchemy nfts 0x...` |
@@ -150,7 +150,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 
 | Command | What it does | Example |
 |---|---|---|
-| `network list` | Lists RPC network IDs for use with `--network` (e.g. `eth-mainnet`) | `alchemy network list --configured` |
+| `network list` | Lists RPC network IDs for use with `--network` (e.g. `eth-mainnet`) | `alchemy network list --search ethereum` |
 | `solana rpc <method> [params...]` | Calls Solana JSON-RPC methods | `alchemy solana rpc getBalance '"<pubkey>"'` |
 | `solana das <method> [params...]` | Calls Solana DAS methods | `alchemy solana das getAssetsByOwner '{"ownerAddress":"<pubkey>"}'` |
 
@@ -251,7 +251,7 @@ Additional env vars:
 | `apps address-allowlist` | `--addresses <addrs>` (required), `--dry-run` |
 | `apps origin-allowlist` | `--origins <origins>` (required), `--dry-run` |
 | `apps ip-allowlist` | `--ips <ips>` (required), `--dry-run` |
-| `network list` | `--configured`, `--app-id <id>` |
+| `network list` | `--mainnet-only`, `--testnet-only`, `--search <term>` |
 | `config reset` | `-y, --yes` |
 
 ## Authentication Reference

package/dist/{auth-PYH5WEC3.js → auth-QB3BA7AN.js}

@@ -3,10 +3,11 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   registerAuth,
   selectAppAfterAuth
-} from "./chunk-DBTRDS35.js";
-import "./chunk-5ZAK2VSS.js";
+} from "./chunk-UMKDYHMO.js";
+import "./chunk-FFMNT74F.js";
 import "./chunk-KDMIWPZH.js";
-import "./chunk-NM25MEJZ.js";
+import "./chunk-ATX65U7J.js";
+import "./chunk-JQRGILIS.js";
 import "./chunk-NBDWF4ZQ.js";
 import "./chunk-BAAQ7ELR.js";
 import "./chunk-56ZVYB4G.js";

package/dist/{auth-76PDHQ3U.js → auth-S4DTOWW3.js}

@@ -2,22 +2,24 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   AUTH_PORT,
-  DEFAULT_EXPIRES_IN_SECONDS,
+  OAUTH_CLIENT_ID,
   exchangeCodeForToken,
-  getLoginUrl,
+  getAuthorizeUrl,
   openBrowser,
   performBrowserLogin,
+  prepareBrowserLogin,
   revokeToken,
   waitForCallback
-} from "./chunk-5ZAK2VSS.js";
+} from "./chunk-FFMNT74F.js";
 import "./chunk-56ZVYB4G.js";
 export {
   AUTH_PORT,
-  DEFAULT_EXPIRES_IN_SECONDS,
+  OAUTH_CLIENT_ID,
   exchangeCodeForToken,
-  getLoginUrl,
+  getAuthorizeUrl,
   openBrowser,
   performBrowserLogin,
+  prepareBrowserLogin,
   revokeToken,
   waitForCallback
 };

package/dist/{chunk-NSG4ZKZI.js → chunk-7GD5HACA.js}

@@ -53,7 +53,7 @@ function semverLT(a, b) {
   return false;
 }
 function currentVersion() {
-  return true ? "0.5.2" : "0.0.0";
+  return true ? "0.6.1" : "0.0.0";
 }
 function toUpdateStatus(latestVersion, checkedAt) {
   const current = currentVersion();

package/dist/{chunk-NM25MEJZ.js → chunk-ATX65U7J.js}

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
+import {
+  getCredentials
+} from "./chunk-JQRGILIS.js";
 import {
   load,
   save
@@ -622,7 +625,17 @@ function resolveAppId(program, cfg) {
   if (config.app?.id) return config.app.id;
   return void 0;
 }
-function resolveAuthToken(cfg) {
+async function resolveAuthToken(cfg) {
+  const creds = await getCredentials();
+  if (creds?.auth_token?.trim()) {
+    if (creds.auth_token_expires_at) {
+      const expiry = new Date(creds.auth_token_expires_at);
+      if (!Number.isNaN(expiry.getTime()) && expiry <= /* @__PURE__ */ new Date()) {
+        return void 0;
+      }
+    }
+    return creds.auth_token;
+  }
   const config = cfg ?? load();
   if (!config.auth_token?.trim()) return void 0;
   if (config.auth_token_expires_at) {
@@ -633,11 +646,11 @@ function resolveAuthToken(cfg) {
   }
   return config.auth_token;
 }
-function adminClientFromFlags(program) {
+async function adminClientFromFlags(program) {
   const cfg = load();
   const accessKey = resolveAccessKey(program, cfg);
   if (accessKey) return new AdminClient(accessKey);
-  const authToken = resolveAuthToken(cfg);
+  const authToken = await resolveAuthToken(cfg);
   if (authToken) return new AdminClient({ type: "auth_token", token: authToken });
   throw errAccessKeyRequired();
 }
@@ -702,7 +715,7 @@ function appNetworkToSlug(rpcUrl) {
 async function resolveConfiguredNetworkSlugs(program, appIdOverride) {
   const appId = appIdOverride || resolveAppId(program);
   if (!appId) throw errAppRequired();
-  const admin = adminClientFromFlags(program);
+  const admin = await adminClientFromFlags(program);
   const app = await admin.getApp(appId);
   const slugs = app.chainNetworks.map((network) => appNetworkToSlug(network.rpcUrl)).filter((slug) => Boolean(slug));
   return Array.from(new Set(slugs)).sort((a, b) => a.localeCompare(b));

package/dist/{chunk-5ZAK2VSS.js → chunk-FFMNT74F.js}

@@ -130,7 +130,7 @@ ${SHARED_STYLE}
 // src/lib/auth.ts
 var AUTH_PORT = 16424;
 var AUTH_CALLBACK_PATH = "/callback";
-var DEFAULT_EXPIRES_IN_SECONDS = 90 * 24 * 60 * 60;
+var OAUTH_CLIENT_ID = "alchemy-cli";
 function getAuthBaseUrl() {
   return process.env.ALCHEMY_AUTH_URL || `https://auth.${getBaseDomain()}`;
 }
@@ -140,14 +140,29 @@ function generateCodeVerifier() {
 function deriveCodeChallenge(verifier) {
   return createHash("sha256").update(verifier).digest("base64url");
 }
-function getLoginUrl(port, codeChallenge) {
+function generateState() {
+  return randomBytes(32).toString("base64url");
+}
+function getAuthorizeUrl(port, codeChallenge, state) {
   const base = getAuthBaseUrl();
-  const redirect = encodeURIComponent(`http://localhost:${port}${AUTH_CALLBACK_PATH}`);
-  let url = `${base}/login?redirectUrl=${redirect}&_t=${Date.now()}`;
-  if (codeChallenge) {
-    url += `&code_challenge=${encodeURIComponent(codeChallenge)}`;
-  }
-  return url;
+  const url = new URL(`${base}/oauth/authorize`);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", OAUTH_CLIENT_ID);
+  url.searchParams.set("redirect_uri", `http://localhost:${port}${AUTH_CALLBACK_PATH}`);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  return url.toString();
+}
+function prepareBrowserLogin(port = AUTH_PORT) {
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = deriveCodeChallenge(codeVerifier);
+  const state = generateState();
+  return {
+    authorizeUrl: getAuthorizeUrl(port, codeChallenge, state),
+    codeVerifier,
+    state
+  };
 }
 function openBrowser(url) {
   const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
@@ -188,6 +203,7 @@ function waitForCallback(port, timeoutMs = 12e4) {
       clearTimeout(timer);
       resolve({
         code,
+        state: url.searchParams.get("state"),
         sendSuccess: () => {
           res.writeHead(200, { "Content-Type": "text/html" });
           res.end(AUTH_SUCCESS_HTML);
@@ -220,43 +236,44 @@ function waitForCallback(port, timeoutMs = 12e4) {
 async function exchangeCodeForToken(code, port, options) {
   const baseUrl = getAuthBaseUrl();
   const redirectUri = `http://localhost:${port}${AUTH_CALLBACK_PATH}`;
-  const body = {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
     code,
-    redirect_uri: redirectUri
-  };
-  if (options?.expiresInSeconds) {
-    body.expires_in_seconds = options.expiresInSeconds;
-  }
-  if (options?.codeVerifier) {
-    body.code_verifier = options.codeVerifier;
-  }
-  const response = await fetch(`${baseUrl}/api/cli/token`, {
+    redirect_uri: redirectUri,
+    client_id: OAUTH_CLIENT_ID,
+    code_verifier: options.codeVerifier
+  });
+  const response = await fetch(`${baseUrl}/oauth/token`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body)
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
   });
   if (!response.ok) {
     const errBody = await response.json().catch(() => ({}));
-    throw new Error(
-      errBody.error || `Token exchange failed (HTTP ${response.status})`
-    );
+    const errMsg = errBody.error_description || errBody.error || `Token exchange failed (HTTP ${response.status})`;
+    throw new Error(errMsg);
   }
   const data = await response.json();
-  if (!data.authToken) {
-    throw new Error("Token exchange response missing authToken");
+  if (!data.access_token) {
+    throw new Error("Token exchange response missing access_token");
   }
-  return { token: data.authToken, expiresAt: data.expiresAt };
+  const expiresAt = new Date(Date.now() + data.expires_in * 1e3).toISOString();
+  return { token: data.access_token, expiresAt };
 }
-async function performBrowserLogin(port = AUTH_PORT, options) {
-  const codeVerifier = generateCodeVerifier();
-  const codeChallenge = deriveCodeChallenge(codeVerifier);
-  const loginUrl = getLoginUrl(port, codeChallenge);
+async function performBrowserLogin(prepared, options) {
+  const port = options?.port ?? AUTH_PORT;
+  const { authorizeUrl, codeVerifier, state } = prepared ?? prepareBrowserLogin(port);
   const callbackPromise = waitForCallback(port);
-  openBrowser(loginUrl);
+  if (!options?.skipBrowserOpen) {
+    openBrowser(authorizeUrl);
+  }
   const callback = await callbackPromise;
+  if (callback.state !== state) {
+    callback.sendError("State mismatch \u2014 possible CSRF attack.");
+    throw new Error("OAuth state mismatch. Authentication aborted.");
+  }
   try {
     const result = await exchangeCodeForToken(callback.code, port, {
-      expiresInSeconds: options?.expiresInSeconds ?? DEFAULT_EXPIRES_IN_SECONDS,
       codeVerifier
     });
     callback.sendSuccess();
@@ -290,8 +307,9 @@ async function revokeToken(token) {
 
 export {
   AUTH_PORT,
-  DEFAULT_EXPIRES_IN_SECONDS,
-  getLoginUrl,
+  OAUTH_CLIENT_ID,
+  getAuthorizeUrl,
+  prepareBrowserLogin,
   openBrowser,
   waitForCallback,
   exchangeCodeForToken,

package/dist/chunk-JQRGILIS.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
+
+// src/lib/credential-storage.ts
+import {
+  getPassword,
+  setPassword,
+  deletePassword,
+  getKeyring,
+  PasswordDeleteError
+} from "cross-keychain";
+var SERVICE = "alchemy-cli";
+var ACCOUNT = "oauth-credentials";
+async function getCredentials() {
+  try {
+    const raw = await getPassword(SERVICE, ACCOUNT);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.auth_token === "string" && typeof parsed.auth_token_expires_at === "string") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function saveCredentials(creds) {
+  await setPassword(SERVICE, ACCOUNT, JSON.stringify(creds));
+}
+async function deleteCredentials() {
+  try {
+    await deletePassword(SERVICE, ACCOUNT);
+  } catch (err) {
+    if (!(err instanceof PasswordDeleteError)) {
+      throw err;
+    }
+  }
+}
+async function getStorageBackend() {
+  try {
+    const keyring = await getKeyring();
+    return keyring.name;
+  } catch {
+    return "unknown";
+  }
+}
+
+export {
+  getCredentials,
+  saveCredentials,
+  deleteCredentials,
+  getStorageBackend
+};

package/dist/{chunk-FM7GQX6U.js → chunk-T5Z2GJUX.js}

@@ -5,7 +5,7 @@ import {
 } from "./chunk-KDMIWPZH.js";
 import {
   resolveAuthToken
-} from "./chunk-NM25MEJZ.js";
+} from "./chunk-ATX65U7J.js";
 import {
   getBaseDomain
 } from "./chunk-56ZVYB4G.js";
@@ -281,14 +281,14 @@ function hasAccessKeyAndApp(cfg) {
 function hasX402Wallet(cfg) {
   return cfg.x402 === true && Boolean(cfg.wallet_key_file?.trim());
 }
-function hasAuthToken(cfg) {
-  return resolveAuthToken(cfg) !== void 0;
+function hasAuthTokenAndApp(cfg) {
+  return resolveAuthToken(cfg) !== void 0 && Boolean(cfg.app?.apiKey);
 }
 function getSetupMethod(cfg) {
   if (hasAPIKey(cfg)) return "api_key";
   if (hasAccessKeyAndApp(cfg)) return "access_key_app";
   if (hasX402Wallet(cfg)) return "x402_wallet";
-  if (hasAuthToken(cfg)) return "auth_token";
+  if (hasAuthTokenAndApp(cfg)) return "auth_token";
   return null;
 }
 function isSetupComplete(cfg) {

package/dist/{chunk-DBTRDS35.js → chunk-UMKDYHMO.js}

@@ -2,17 +2,25 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   AUTH_PORT,
-  getLoginUrl,
-  performBrowserLogin,
-  revokeToken
-} from "./chunk-5ZAK2VSS.js";
+  exchangeCodeForToken,
+  openBrowser,
+  prepareBrowserLogin,
+  revokeToken,
+  waitForCallback
+} from "./chunk-FFMNT74F.js";
 import {
   isInteractiveAllowed
 } from "./chunk-KDMIWPZH.js";
 import {
   AdminClient,
   resolveAuthToken
-} from "./chunk-NM25MEJZ.js";
+} from "./chunk-ATX65U7J.js";
+import {
+  deleteCredentials,
+  getCredentials,
+  getStorageBackend,
+  saveCredentials
+} from "./chunk-JQRGILIS.js";
 import {
   bold,
   brand,
@@ -23,7 +31,6 @@ import {
   withSpinner
 } from "./chunk-NBDWF4ZQ.js";
 import {
-  configPath,
   load,
   maskIf,
   save
@@ -44,7 +51,7 @@ function registerAuth(program) {
     const yes = opts.yes || cmd.opts().yes;
     try {
       if (!opts.force) {
-        const existing = resolveAuthToken();
+        const existing = await resolveAuthToken();
         if (existing) {
           printHuman(
             `  ${green("\u2713")} Already authenticated
@@ -57,48 +64,89 @@ function registerAuth(program) {
         }
       }
       if (opts.force) {
-        const cfg2 = load();
-        if (cfg2.auth_token) {
-          await revokeToken(cfg2.auth_token);
-          save({ ...cfg2, auth_token: void 0, auth_token_expires_at: void 0 });
+        const existingCreds = await getCredentials();
+        const tokenToRevoke = existingCreds?.auth_token;
+        if (!tokenToRevoke) {
+          const cfg2 = load();
+          if (cfg2.auth_token) {
+            await revokeToken(cfg2.auth_token);
+            save({ ...cfg2, auth_token: void 0, auth_token_expires_at: void 0 });
+          }
+        } else {
+          await revokeToken(tokenToRevoke);
         }
+        await deleteCredentials();
       }
+      const prepared = prepareBrowserLogin();
+      const callbackPromise = waitForCallback(AUTH_PORT);
       if (!isJSONMode()) {
         console.log("");
         console.log(`  ${brand("\u25C6")} ${bold("Alchemy Authentication")}`);
         console.log(`  ${dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500")}`);
         console.log("");
-        console.log(`  ${dim(getLoginUrl(AUTH_PORT))}`);
+        console.log(`  ${dim(prepared.authorizeUrl)}`);
         console.log("");
       }
+      let browserOpened = false;
       if (!yes && !isJSONMode() && isInteractiveAllowed(program)) {
-        const answer = await promptText({
-          message: "Press Enter to open browser and link your Alchemy account",
-          cancelMessage: "Login cancelled."
-        });
-        if (answer === null) return;
+        const promptResult = await Promise.race([
+          promptText({
+            message: "Press Enter to open browser, or paste the URL above to log in manually",
+            cancelMessage: "Login cancelled."
+          }),
+          callbackPromise.then(() => "callback_received")
+        ]);
+        if (promptResult === null) return;
+        if (promptResult !== "callback_received") {
+          if (!isJSONMode()) {
+            console.log(`  Opening browser to log in...`);
+            console.log(`  ${dim("Waiting for authentication...")}`);
+          }
+          openBrowser(prepared.authorizeUrl);
+          browserOpened = true;
+        }
       }
-      if (!isJSONMode()) {
-        console.log(`  Opening browser to log in...`);
-        console.log(`  ${dim("Waiting for authentication...")}`);
+      if (!browserOpened && yes) {
+        if (!isJSONMode()) {
+          console.log(`  Opening browser to log in...`);
+          console.log(`  ${dim("Waiting for authentication...")}`);
+        }
+        openBrowser(prepared.authorizeUrl);
       }
-      const result = await performBrowserLogin();
-      const cfg = load();
-      save({
-        ...cfg,
+      const callback = await callbackPromise;
+      if (callback.state !== prepared.state) {
+        callback.sendError("State mismatch \u2014 possible CSRF attack.");
+        throw new Error("OAuth state mismatch. Authentication aborted.");
+      }
+      let result;
+      try {
+        result = await exchangeCodeForToken(callback.code, AUTH_PORT, {
+          codeVerifier: prepared.codeVerifier
+        });
+        callback.sendSuccess();
+      } catch (err) {
+        callback.sendError("Failed to complete authentication. Please try again.");
+        throw err;
+      }
+      await saveCredentials({
         auth_token: result.token,
         auth_token_expires_at: result.expiresAt
       });
+      const cfg = load();
+      if (cfg.auth_token) {
+        save({ ...cfg, auth_token: void 0, auth_token_expires_at: void 0 });
+      }
       const expiresAt = result.expiresAt;
+      const backend = await getStorageBackend();
       printHuman(
         `  ${green("\u2713")} Logged in successfully
-  ${dim("Token saved to")} ${configPath()}
+  ${dim("Credentials stored in")} ${backend}
   ${dim("Expires:")} ${expiresAt}
 `,
         {
           status: "authenticated",
           expiresAt,
-          configPath: configPath()
+          storageBackend: backend
         }
       );
       if (isInteractiveAllowed(program)) {
@@ -111,11 +159,13 @@ function registerAuth(program) {
       );
     }
   });
-  cmd.command("status").description("Show current authentication status").action(() => {
+  cmd.command("status").description("Show current authentication status").action(async () => {
     try {
+      const creds = await getCredentials();
       const cfg = load();
-      const validToken = resolveAuthToken(cfg);
-      if (!cfg.auth_token) {
+      const validToken = await resolveAuthToken(cfg);
+      const hasToken = creds?.auth_token || cfg.auth_token;
+      if (!hasToken) {
         printHuman(
           `  ${dim("Not authenticated. Run")} alchemy auth ${dim("to log in.")}
 `,
@@ -131,15 +181,20 @@ function registerAuth(program) {
         );
         return;
       }
+      const expiresAt = creds?.auth_token_expires_at || cfg.auth_token_expires_at || "unknown";
+      const backend = await getStorageBackend();
+      const storedIn = creds?.auth_token ? backend : "config file (legacy)";
       printHuman(
         `  ${green("\u2713")} Authenticated
   ${dim("Token:")} ${maskIf(validToken)}
-  ${dim("Expires:")} ${cfg.auth_token_expires_at || "unknown"}
+  ${dim("Storage:")} ${storedIn}
+  ${dim("Expires:")} ${expiresAt}
 `,
         {
           authenticated: true,
           expired: false,
-          expiresAt: cfg.auth_token_expires_at
+          expiresAt,
+          storageBackend: storedIn
         }
       );
     } catch (err) {
@@ -148,14 +203,17 @@ function registerAuth(program) {
   });
   cmd.command("logout").description("Clear saved authentication token").action(async () => {
     try {
+      const creds = await getCredentials();
       const cfg = load();
+      const activeToken = creds?.auth_token || cfg.auth_token;
       let revokeResult;
-      if (cfg.auth_token) {
-        revokeResult = await revokeToken(cfg.auth_token);
+      if (activeToken) {
+        revokeResult = await revokeToken(activeToken);
       }
-      const { auth_token: _, auth_token_expires_at: __, ...rest } = cfg;
+      await deleteCredentials();
+      const { auth_token: _, auth_token_expires_at: __, app: ___, ...rest } = cfg;
       save(rest);
-      if (!cfg.auth_token) {
+      if (!activeToken) {
         printHuman(
           `  ${dim("No active session.")}
 `,

package/dist/credential-storage-T6FFW7DG.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
+import {
+  deleteCredentials,
+  getCredentials,
+  getStorageBackend,
+  saveCredentials
+} from "./chunk-JQRGILIS.js";
+export {
+  deleteCredentials,
+  getCredentials,
+  getStorageBackend,
+  saveCredentials
+};

package/dist/index.js

@@ -2,15 +2,15 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   registerAuth
-} from "./chunk-DBTRDS35.js";
-import "./chunk-5ZAK2VSS.js";
+} from "./chunk-UMKDYHMO.js";
+import "./chunk-FFMNT74F.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   nativeTokenSymbol,
   shouldRunOnboarding
-} from "./chunk-FM7GQX6U.js";
+} from "./chunk-T5Z2GJUX.js";
 import {
   isInteractiveAllowed
 } from "./chunk-KDMIWPZH.js";
@@ -23,12 +23,13 @@ import {
   resolveNetwork,
   resolveWalletKey,
   resolveX402Client
-} from "./chunk-NM25MEJZ.js";
+} from "./chunk-ATX65U7J.js";
+import "./chunk-JQRGILIS.js";
 import {
   getAvailableUpdate,
   getUpdateStatus,
   printUpdateNotice
-} from "./chunk-NSG4ZKZI.js";
+} from "./chunk-7GD5HACA.js";
 import {
   bold,
   brand,
@@ -559,9 +560,15 @@ function registerConfig(program2) {
       printJSON(toMap(cfg));
       return;
     }
-    const { resolveAuthToken } = await import("./resolve-CLDYJ27A.js");
-    const validToken = resolveAuthToken(cfg);
-    const authStatus = cfg.auth_token ? validToken ? `${green("\u2713")} authenticated${cfg.auth_token_expires_at ? ` ${dim(`(expires ${cfg.auth_token_expires_at})`)}` : ""}` : `${yellow("\u25C6")} expired${cfg.auth_token_expires_at ? ` ${dim(`(${cfg.auth_token_expires_at})`)}` : ""}` : dim("(not set) \u2014 run 'alchemy auth' to log in");
+    const { resolveAuthToken } = await import("./resolve-HXKHDOJZ.js");
+    const { getCredentials, getStorageBackend } = await import("./credential-storage-T6FFW7DG.js");
+    const validToken = await resolveAuthToken(cfg);
+    const creds = await getCredentials();
+    const hasToken = creds?.auth_token || cfg.auth_token;
+    const expiresAt = creds?.auth_token_expires_at || cfg.auth_token_expires_at;
+    const backend = await getStorageBackend();
+    const storageName = creds?.auth_token ? backend : cfg.auth_token ? "config (legacy)" : "";
+    const authStatus = hasToken ? validToken ? `${green("\u2713")} authenticated${expiresAt ? ` ${dim(`(expires ${expiresAt})`)}` : ""}${storageName ? ` ${dim(`[${storageName}]`)}` : ""}` : `${yellow("\u25C6")} expired${expiresAt ? ` ${dim(`(${expiresAt})`)}` : ""}` : dim("(not set) \u2014 run 'alchemy auth' to log in");
     const pairs = [
       ["auth", authStatus],
       [
@@ -642,7 +649,7 @@ function registerConfig(program2) {
 
 // src/commands/rpc.ts
 function registerRPC(program2) {
-  program2.command("rpc").argument("<method>", "JSON-RPC method name (e.g. eth_blockNumber)").argument("[params...]", "Method parameters as JSON values").description("Make a raw JSON-RPC call").addHelpText(
+  program2.command("rpc").argument("<method>", "JSON-RPC method name (e.g. eth_blockNumber)").argument("[params...]", "Method parameters as JSON values").description("Sends a raw JSON-RPC request to an Alchemy node (e.g. eth_call, eth_getCode, eth_blockNumber). Use for low-level RPC calls only. For higher-level operations like balances, transfers, simulation, or token data, use the dedicated subcommands instead.").addHelpText(
     "after",
     `
 Examples:
@@ -722,7 +729,7 @@ function resolveBlockParam(block) {
   return blockParam;
 }
 function registerBalance(program2) {
-  program2.command("balance").argument("[address]", "Wallet address (0x...) or ENS name, or pipe via stdin").alias("bal").description("Get the native token balance of an address").addHelpText(
+  program2.command("balance").argument("[address]", "Wallet address (0x...) or ENS name, or pipe via stdin").alias("bal").description("Returns the native token balance (ETH, MATIC, etc.) for any wallet address or ENS name. Use when the user wants to know how much native currency a wallet holds. Does NOT return ERC-20 tokens \u2014 use `alchemy tokens balances` for that.").addHelpText(
     "after",
     `
 Examples:
@@ -1052,7 +1059,7 @@ function formatNFTRows(nfts) {
   ]);
 }
 function registerNFTs(program2) {
-  const cmd = program2.command("nfts").description("NFT API wrappers").argument("[address]", "Wallet address or ENS name (default action: list owned NFTs)").option("--limit <n>", "Maximum number of NFTs to return per page", parseInt).option("--page-key <key>", "Pagination key from a previous response").addHelpText(
+  const cmd = program2.command("nfts").description("Lists all NFTs owned by a wallet address on the current network via the Alchemy NFT API. Use for single-network NFT ownership queries. For all NFTs across multiple networks in a portfolio view, use `alchemy portfolio nfts`.").argument("[address]", "Wallet address or ENS name (default action: list owned NFTs)").option("--limit <n>", "Maximum number of NFTs to return per page", parseInt).option("--page-key <key>", "Pagination key from a previous response").addHelpText(
     "after",
     `
 Examples:
@@ -1515,7 +1522,7 @@ function registerApps(program2) {
   const cmd = program2.command("apps").description("Manage Alchemy apps");
   cmd.command("list").description("List all apps").option("--cursor <cursor>", "Pagination cursor").option("--limit <n>", "Max results per page", parseInt).option("--all", "Fetch all pages").option("--search <query>", "Search apps by name or id (client-side)").option("--id <appId>", "Filter by exact app id (client-side)").action(async (opts) => {
     try {
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const fetchAll = Boolean(opts.all);
       const hasSearch = typeof opts.search === "string";
       const hasId = typeof opts.id === "string";
@@ -1642,7 +1649,7 @@ function registerApps(program2) {
   });
   cmd.command("get <id>").description("Get app details").action(async (id) => {
     try {
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Fetching app\u2026",
         "App fetched",
@@ -1676,7 +1683,7 @@ function registerApps(program2) {
         ...products && { products }
       };
       if (handleDryRun(opts, "create", payload, `Would create app "${opts.name}" on networks: ${networks.join(", ")}`)) return;
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Creating app\u2026",
         "App created",
@@ -1715,7 +1722,7 @@ function registerApps(program2) {
           return;
         }
       }
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       await withSpinner(
         "Deleting app\u2026",
         "App deleted",
@@ -1741,7 +1748,7 @@ function registerApps(program2) {
         ...opts.description && { description: opts.description }
       };
       if (handleDryRun(opts, "update", payload, `Would update app ${id}`)) return;
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Updating app\u2026",
         "App updated",
@@ -1763,7 +1770,7 @@ function registerApps(program2) {
     try {
       const networks = splitCommaList(opts.networks);
       if (handleDryRun(opts, "networks", { id, networks }, `Would update networks for app ${id}: ${networks.join(", ")}`)) return;
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Updating networks\u2026",
         "Networks updated",
@@ -1784,7 +1791,7 @@ function registerApps(program2) {
     try {
       const entries = splitCommaList(opts.addresses).map((s) => ({ value: s }));
       if (handleDryRun(opts, "address-allowlist", { id, addresses: entries }, `Would update address allowlist for app ${id}`)) return;
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Updating address allowlist\u2026",
         "Address allowlist updated",
@@ -1805,7 +1812,7 @@ function registerApps(program2) {
     try {
       const entries = splitCommaList(opts.origins).map((s) => ({ value: s }));
       if (handleDryRun(opts, "origin-allowlist", { id, origins: entries }, `Would update origin allowlist for app ${id}`)) return;
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Updating origin allowlist\u2026",
         "Origin allowlist updated",
@@ -1826,7 +1833,7 @@ function registerApps(program2) {
     try {
       const entries = splitCommaList(opts.ips).map((s) => ({ value: s }));
       if (handleDryRun(opts, "ip-allowlist", { id, ips: entries }, `Would update IP allowlist for app ${id}`)) return;
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const app = await withSpinner(
         "Updating IP allowlist\u2026",
         "IP allowlist updated",
@@ -1845,7 +1852,7 @@ function registerApps(program2) {
   });
   cmd.command("configured-networks").description("List RPC network slugs configured for an app").option("--app-id <id>", "App ID (overrides saved app)").action(async (opts) => {
     try {
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const appId = opts.appId || resolveAppId(program2);
       if (!appId) throw errAppRequired();
       const app = await withSpinner(
@@ -1876,7 +1883,7 @@ function registerApps(program2) {
   });
   cmd.command("select [id]").description("Select an app to use as the default").action(async (id) => {
     try {
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       let selected;
       if (id) {
         selected = await withSpinner(
@@ -1934,7 +1941,7 @@ function registerApps(program2) {
   });
   cmd.command("chains").description("List Admin API chain identifiers for app configuration (e.g. ETH_MAINNET)").action(async () => {
     try {
-      const admin = adminClientFromFlags(program2);
+      const admin = await adminClientFromFlags(program2);
       const chains = await withSpinner(
         "Fetching chains\u2026",
         "Chains fetched",
@@ -2050,7 +2057,7 @@ function registerWallet(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("address").description("Display the address of the configured wallet").action(() => {
+  cmd.command("address").description("Display the address of the locally configured x402 wallet. This shows the CLI's own signing wallet only \u2014 it does NOT look up arbitrary addresses. To check a wallet's ETH balance, use `alchemy balance`.").action(() => {
     try {
       const key = resolveWalletKey(program2);
       if (!key) throw errWalletKeyRequired();
@@ -2075,9 +2082,15 @@ function registerSetup(program2) {
       printJSON(status);
       return;
     }
+    const methodLabels = {
+      api_key: "API key",
+      access_key_app: "Access key + app",
+      x402_wallet: "SIWx wallet",
+      auth_token: "Browser login + app"
+    };
     printKeyValueBox([
       ["Complete", status.complete ? "yes" : "no"],
-      ["Satisfied by", status.satisfiedBy ?? dim("(none)")]
+      ["Satisfied by", status.satisfiedBy ? methodLabels[status.satisfiedBy] ?? status.satisfiedBy : dim("(none)")]
     ]);
     if (status.missing.length > 0) {
       console.log("");
@@ -2189,7 +2202,7 @@ function formatTransferRows(transfers) {
   });
 }
 function registerTransfers(program2) {
-  program2.command("transfers").argument("[address]", "Wallet address or ENS name \u2014 queries outgoing transfers (use --to-address for incoming)").description("Get transfer history (alchemy_getAssetTransfers)").option("--from-address <address>", "Filter sender address").option("--to-address <address>", "Filter recipient address").option("--from-block <block>", "Start block (default: 0x0)").option("--to-block <block>", "End block (default: latest)").option("--category <list>", "Comma-separated categories (erc20,erc721,erc1155,external,internal,specialnft)").option("--max-count <hexOrDecimal>", "Max records to return per page").option("--page-key <key>", "Pagination key").addHelpText(
+  program2.command("transfers").argument("[address]", "Wallet address or ENS name \u2014 queries outgoing transfers (use --to-address for incoming)").description("Lists all asset transfer transactions for a wallet address \u2014 ERC-20, ERC-721, ERC-1155, and native (ETH) transfers. Use for transaction history or transfer activity. Does NOT return current balances \u2014 use `alchemy balance` or `alchemy tokens balances` for that.").option("--from-address <address>", "Filter sender address").option("--to-address <address>", "Filter recipient address").option("--from-block <block>", "Start block (default: 0x0)").option("--to-block <block>", "End block (default: latest)").option("--category <list>", "Comma-separated categories (erc20,erc721,erc1155,external,internal,specialnft)").option("--max-count <hexOrDecimal>", "Max records to return per page").option("--page-key <key>", "Pagination key").addHelpText(
     "after",
     `
 Examples:
@@ -2411,7 +2424,7 @@ async function runDataCall(program2, title, path, body) {
 }
 function registerPortfolio(program2) {
   const cmd = program2.command("portfolio").description("Portfolio API wrappers");
-  cmd.command("tokens").description("Get token portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/tokens/by-address").action(async (opts) => {
+  cmd.command("tokens").description("Returns all ERC-20 token holdings and their USD values across one or more networks for a wallet address. Use for a portfolio view of fungible token assets. For a single-network NFT list, use `alchemy nfts`; for native token balance, use `alchemy balance`.").requiredOption("--body <json>", "JSON body for /assets/tokens/by-address").action(async (opts) => {
     try {
       const result = await runDataCall(
         program2,
@@ -2439,7 +2452,7 @@ function registerPortfolio(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("nfts").description("Get NFT portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/by-address").action(async (opts) => {
+  cmd.command("nfts").description("Returns all NFTs owned by a wallet address across one or more networks. Use to list all NFTs a wallet holds in a portfolio view. For metadata on a specific NFT by contract + token ID, use `alchemy nfts metadata`.").requiredOption("--body <json>", "JSON body for /assets/nfts/by-address").action(async (opts) => {
     try {
       const result = await runDataCall(
         program2,
@@ -2481,7 +2494,7 @@ async function runSimulateCall(program2, options) {
 }
 function registerSimulate(program2) {
   const cmd = program2.command("simulate").description("Simulation API wrappers");
-  cmd.command("asset-changes").description("Call alchemy_simulateAssetChanges").requiredOption("--tx <json>", "Transaction object JSON").option("--block-tag <tag>", "Block tag (default latest)", "latest").action(async (opts) => {
+  cmd.command("asset-changes").description("Simulates a transaction and returns a human-readable breakdown of asset changes (token transfers, ETH movements, NFT transfers) before it is broadcast. Use to preview what a transaction will do. For raw JSON-RPC calls, use `alchemy rpc` instead.").requiredOption("--tx <json>", "Transaction object JSON").option("--block-tag <tag>", "Block tag (default latest)", "latest").action(async (opts) => {
     try {
       await runSimulateCall(program2, {
         method: "alchemy_simulateAssetChanges",
@@ -2531,7 +2544,7 @@ function resolveWebhookApiKey(opts) {
 function registerWebhooks(program2) {
   const cmd = program2.command("webhooks").description("Notify API wrappers");
   cmd.option("--webhook-api-key <key>", "Webhook API key").option("--notify-token <token>", "Deprecated alias for webhook API key");
-  cmd.command("list").description("List team webhooks").action(async () => {
+  cmd.command("list").description("Lists all existing Alchemy webhooks configured for this team. Use to view or audit registered webhooks. Does NOT create webhooks \u2014 use `alchemy webhooks create` for that.").action(async () => {
     try {
       const token = resolveWebhookApiKey(cmd.opts());
       const result = await withSpinner(
@@ -2545,7 +2558,7 @@ function registerWebhooks(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("create").description("Create webhook").requiredOption("--body <json>", "Create webhook JSON payload").option("--dry-run", "Preview without executing").action(async (opts) => {
+  cmd.command("create").description("Creates a new Alchemy webhook subscription for a given event type (address activity, mined transactions, dropped transactions, etc.). Use this to register a new webhook endpoint. To view existing webhooks, use `alchemy webhooks list`.").requiredOption("--body <json>", "Create webhook JSON payload").option("--dry-run", "Preview without executing").action(async (opts) => {
     try {
       const payload = parseRequiredJSON(opts.body, "--body");
       if (opts.dryRun) {
@@ -3183,7 +3196,7 @@ function buildAgentPrompt(program2) {
         envVar: "ALCHEMY_ACCESS_KEY",
         flag: "--access-key <key>",
         configKey: "access-key",
-        commandFamilies: ["apps", "network list --configured"]
+        commandFamilies: ["apps", "apps configured-networks"]
       },
       {
         method: "Webhook API key",
@@ -3384,7 +3397,7 @@ function resetUpdateNoticeState() {
 }
 program.name("alchemy").description(
   "The Alchemy CLI lets you query blockchain data, call JSON-RPC methods, and manage your Alchemy configuration."
-).version("0.5.2", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option("--access-key <key>", "Alchemy access key (env: ALCHEMY_ACCESS_KEY)").option(
+).version("0.6.1", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option("--access-key <key>", "Alchemy access key (env: ALCHEMY_ACCESS_KEY)").option(
   "-n, --network <network>",
   "Target network (default: eth-mainnet) (env: ALCHEMY_NETWORK)"
 ).option("--x402", "Use x402 wallet-based gateway auth").option("--wallet-key-file <path>", "Path to wallet private key file for x402").option("--json", "Force JSON output (auto-enabled when piped)").option("-q, --quiet", "Suppress non-essential output").option("--verbose", "Enable verbose output").option("--no-color", "Disable color output").option("--reveal", "Show secrets in plain text").option("--timeout <ms>", "Request timeout in milliseconds (default: none)", parseInt).option("--debug", "Enable debug diagnostics").option("--no-interactive", "Disable REPL and prompt-driven interactions").addHelpCommand(false).allowExcessArguments(true).exitOverride((err) => {
@@ -3552,11 +3565,11 @@ ${styledLine}`;
     "wallet"
   ];
   if (!skipAppPrompt.includes(cmdName) && isInteractiveAllowed(program) && !opts.apiKey && !process.env.ALCHEMY_API_KEY) {
-    const { resolveAuthToken } = await import("./resolve-CLDYJ27A.js");
-    const authToken = resolveAuthToken(cfg);
+    const { resolveAuthToken } = await import("./resolve-HXKHDOJZ.js");
+    const authToken = await resolveAuthToken(cfg);
     const hasApiKey = Boolean(cfg.api_key?.trim() || cfg.app?.apiKey);
     if (authToken && !hasApiKey) {
-      const { selectAppAfterAuth } = await import("./auth-PYH5WEC3.js");
+      const { selectAppAfterAuth } = await import("./auth-QB3BA7AN.js");
       console.log("");
       console.log(`  No app selected. Please select an app to continue.`);
       await selectAppAfterAuth(authToken);
@@ -3587,7 +3600,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-DNEXVUUH.js");
+      const { runOnboarding } = await import("./onboarding-3WIM6PVV.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -3599,7 +3612,7 @@ ${styledLine}`;
       latestForInteractiveStartup = getAvailableUpdateOnce();
       updateShownDuringInteractiveStartup = Boolean(latestForInteractiveStartup);
     }
-    const { startREPL } = await import("./interactive-CGEVIPC2.js");
+    const { startREPL } = await import("./interactive-QJ4REXWB.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {

package/dist/{interactive-CGEVIPC2.js → interactive-QJ4REXWB.js}

@@ -3,12 +3,13 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getRPCNetworkIds,
   getSetupMethod
-} from "./chunk-FM7GQX6U.js";
+} from "./chunk-T5Z2GJUX.js";
 import "./chunk-KDMIWPZH.js";
-import "./chunk-NM25MEJZ.js";
+import "./chunk-ATX65U7J.js";
+import "./chunk-JQRGILIS.js";
 import {
   getUpdateNoticeLines
-} from "./chunk-NSG4ZKZI.js";
+} from "./chunk-7GD5HACA.js";
 import {
   bold,
   brand,
@@ -127,7 +128,7 @@ function formatSetupMethodLabel() {
   if (method === "api_key") return "API key";
   if (method === "access_key_app") return "Access key + app";
   if (method === "x402_wallet") return "SIWx wallet";
-  if (method === "auth_token") return "Auth token";
+  if (method === "auth_token") return "Browser login + app";
   return "Not configured";
 }
 function replHistoryPath() {

package/dist/{onboarding-DNEXVUUH.js → onboarding-3WIM6PVV.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getUpdateNoticeLines
-} from "./chunk-NSG4ZKZI.js";
+} from "./chunk-7GD5HACA.js";
 import {
   bold,
   brand,
@@ -11,10 +11,7 @@ import {
   green,
   promptText
 } from "./chunk-NBDWF4ZQ.js";
-import {
-  load,
-  save
-} from "./chunk-BAAQ7ELR.js";
+import "./chunk-BAAQ7ELR.js";
 import "./chunk-56ZVYB4G.js";
 
 // src/commands/onboarding.ts
@@ -38,20 +35,20 @@ async function runOnboarding(_program, latestUpdate = null) {
   if (answer === null) {
     return false;
   }
-  const { performBrowserLogin, AUTH_PORT, getLoginUrl } = await import("./auth-76PDHQ3U.js");
+  const { performBrowserLogin, prepareBrowserLogin } = await import("./auth-S4DTOWW3.js");
+  const prepared = prepareBrowserLogin();
   console.log(`  Opening browser to log in...`);
-  console.log(`  ${dim(getLoginUrl(AUTH_PORT))}`);
+  console.log(`  ${dim(prepared.authorizeUrl)}`);
   console.log(`  ${dim("Waiting for authentication...")}`);
   try {
-    const result = await performBrowserLogin();
-    const cfg = load();
-    save({
-      ...cfg,
+    const result = await performBrowserLogin(prepared);
+    const { saveCredentials } = await import("./credential-storage-T6FFW7DG.js");
+    await saveCredentials({
       auth_token: result.token,
       auth_token_expires_at: result.expiresAt
     });
     console.log(`  ${green("\u2713")} Logged in successfully`);
-    const { selectAppAfterAuth } = await import("./auth-PYH5WEC3.js");
+    const { selectAppAfterAuth } = await import("./auth-QB3BA7AN.js");
     await selectAppAfterAuth(result.token);
     return true;
   } catch (err) {

package/dist/{resolve-CLDYJ27A.js → resolve-HXKHDOJZ.js}

@@ -12,7 +12,8 @@ import {
   resolveWalletKey,
   resolveX402,
   resolveX402Client
-} from "./chunk-NM25MEJZ.js";
+} from "./chunk-ATX65U7J.js";
+import "./chunk-JQRGILIS.js";
 import "./chunk-BAAQ7ELR.js";
 import "./chunk-56ZVYB4G.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy/cli",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Alchemy CLI — interact with blockchain data",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "@noble/hashes": "^2.0.1",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
+    "cross-keychain": "^1.1.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {