@alchemy/cli 0.3.1 → 0.5.0

package/dist/index.js

@@ -1,37 +1,66 @@
 #!/usr/bin/env node
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
-  adminClientFromFlags,
-  clientFromFlags,
-  fetchWithTimeout,
+  registerAuth
+} from "./chunk-LYUW7O6X.js";
+import "./chunk-IGD4NIK7.js";
+import {
   readStdinArg,
+  readStdinLines,
   registerConfig,
   registerWallet,
-  resolveAPIKey,
   resolveAddress,
-  resolveAppId,
-  resolveConfiguredNetworkSlugs,
-  resolveNetwork,
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-J6RZM4CJ.js";
+} from "./chunk-44OGGLN4.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   nativeTokenSymbol,
   shouldRunOnboarding
-} from "./chunk-QDDJ3OYO.js";
+} from "./chunk-5X6YRTPU.js";
 import {
-  EXIT_CODES,
-  ErrorCode,
+  getAvailableUpdate,
+  getUpdateStatus,
+  printUpdateNotice
+} from "./chunk-DUQFOLLZ.js";
+import {
+  adminClientFromFlags,
   bold,
   brand,
   brandedHelp,
-  debug,
+  clientFromFlags,
   dim,
   emptyState,
+  etherscanTxURL,
+  failBadge,
+  green,
+  isInteractiveAllowed,
+  load,
+  maskIf,
+  printKeyValueBox,
+  printSyntaxJSON,
+  printTable,
+  promptConfirm,
+  promptSelect,
+  red,
+  resolveAPIKey,
+  resolveAppId,
+  resolveNetwork,
+  resolveX402Client,
+  save,
+  successBadge,
+  timeAgo,
+  weiToEth,
+  withSpinner
+} from "./chunk-T2XSNZE3.js";
+import {
+  EXIT_CODES,
+  ErrorCode,
+  debug,
+  errAppRequired,
   errAuthRequired,
   errInvalidAPIKey,
   errInvalidArgs,
@@ -40,37 +69,20 @@ import {
   errRateLimited,
   errSetupRequired,
   esc,
-  etherscanTxURL,
   exitWithError,
-  failBadge,
+  fetchWithTimeout,
   formatCommanderError,
-  getAvailableUpdate,
-  getUpdateStatus,
-  green,
+  getBaseDomain,
   identity,
-  isInteractiveAllowed,
   isJSONMode,
-  load,
-  maskIf,
   noColor,
   printHuman,
   printJSON,
-  printKeyValueBox,
-  printSyntaxJSON,
-  printTable,
-  printUpdateNotice,
-  promptConfirm,
-  promptSelect,
   quiet,
-  red,
   setFlags,
   setNoColor,
-  successBadge,
-  timeAgo,
-  verbose,
-  weiToEth,
-  withSpinner
-} from "./chunk-6XTLILDF.js";
+  verbose
+} from "./chunk-56ZVYB4G.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -108,6 +120,54 @@ Examples:
 }
 
 // src/commands/balance.ts
+async function fetchBalance(program2, addressInput, blockParam) {
+  const client = clientFromFlags(program2);
+  const address = await resolveAddress(addressInput, client);
+  const result = await withSpinner(
+    "Fetching balance\u2026",
+    "Balance fetched",
+    () => client.call("eth_getBalance", [address, blockParam])
+  );
+  const wei = BigInt(result);
+  const network = resolveNetwork(program2);
+  const symbol = nativeTokenSymbol(network);
+  if (isJSONMode()) {
+    printJSON({
+      address,
+      wei: wei.toString(),
+      balance: weiToEth(wei),
+      symbol,
+      network
+    });
+  } else {
+    printKeyValueBox([
+      ["Address", address],
+      ["Balance", green(`${weiToEth(wei)} ${symbol}`)],
+      ["Network", network]
+    ]);
+    if (verbose) {
+      console.log("");
+      printJSON({
+        rpcMethod: "eth_getBalance",
+        rpcParams: [address, blockParam],
+        rpcResult: result
+      });
+    }
+  }
+}
+function resolveBlockParam(block) {
+  let blockParam = block ?? "latest";
+  if (blockParam !== "latest" && blockParam !== "earliest" && blockParam !== "pending") {
+    if (!blockParam.startsWith("0x")) {
+      const num = parseInt(blockParam, 10);
+      if (isNaN(num) || num < 0) {
+        throw errInvalidArgs("Block must be a number, hex, or tag (latest, earliest, pending).");
+      }
+      blockParam = `0x${num.toString(16)}`;
+    }
+  }
+  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(
     "after",
@@ -117,51 +177,21 @@ Examples:
   alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n polygon-mainnet
   echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy balance
   alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --block 15537393
-  alchemy balance vitalik.eth`
+  alchemy balance vitalik.eth
+  cat addresses.txt | alchemy balance`
   ).option("--block <block>", "Block number, hex, or tag (default: latest)").action(async (addressArg, opts) => {
     try {
-      const addressInput = addressArg ?? await readStdinArg("address");
-      const client = clientFromFlags(program2);
-      const address = await resolveAddress(addressInput, client);
-      let blockParam = opts?.block ?? "latest";
-      if (blockParam !== "latest" && blockParam !== "earliest" && blockParam !== "pending") {
-        if (!blockParam.startsWith("0x")) {
-          const num = parseInt(blockParam, 10);
-          if (isNaN(num) || num < 0) {
-            throw errInvalidArgs("Block must be a number, hex, or tag (latest, earliest, pending).");
-          }
-          blockParam = `0x${num.toString(16)}`;
-        }
+      const blockParam = resolveBlockParam(opts?.block);
+      if (addressArg) {
+        await fetchBalance(program2, addressArg, blockParam);
+        return;
       }
-      const result = await withSpinner(
-        "Fetching balance\u2026",
-        "Balance fetched",
-        () => client.call("eth_getBalance", [address, blockParam])
-      );
-      const wei = BigInt(result);
-      const network = resolveNetwork(program2);
-      const symbol = nativeTokenSymbol(network);
-      if (isJSONMode()) {
-        printJSON({
-          address,
-          wei: wei.toString(),
-          balance: weiToEth(wei),
-          symbol,
-          network
-        });
-      } else {
-        printKeyValueBox([
-          ["Address", address],
-          ["Balance", green(`${weiToEth(wei)} ${symbol}`)],
-          ["Network", network]
-        ]);
-        if (verbose) {
-          console.log("");
-          printJSON({
-            rpcMethod: "eth_getBalance",
-            rpcParams: [address, "latest"],
-            rpcResult: result
-          });
+      const lines = await readStdinLines("address");
+      for (const line of lines) {
+        try {
+          await fetchBalance(program2, line, blockParam);
+        } catch (err) {
+          exitWithError(err);
         }
       }
     } catch (err) {
@@ -239,29 +269,28 @@ function formatGasSummary(gasUsed, gasLimit, options) {
 
 // src/commands/tx.ts
 function registerTx(program2) {
-  program2.command("tx").argument("[hash]", "Transaction hash (0x...) or pipe via stdin").description("Get transaction details by hash").addHelpText(
+  program2.command("tx").argument("[hash]", "Transaction hash (0x...) or pipe via stdin").description("Get transaction details by hash (use 'receipt' for receipt data)").addHelpText(
     "after",
     `
 Examples:
   alchemy tx 0xabc123...
-  echo 0xabc123... | alchemy tx`
+  echo 0xabc123... | alchemy tx
+
+Tip: use 'alchemy receipt <hash>' to get the transaction receipt (status, gas used, logs).`
   ).action(async (hashArg) => {
     try {
       const hash = hashArg ?? await readStdinArg("hash");
       validateTxHash(hash);
       const client = clientFromFlags(program2);
-      const [tx, receipt] = await withSpinner("Fetching transaction\u2026", "Transaction fetched", async () => {
+      const tx = await withSpinner("Fetching transaction\u2026", "Transaction fetched", async () => {
         const t = await client.call("eth_getTransactionByHash", [
           hash
         ]);
         if (!t) throw errNotFound(`transaction ${hash}`);
-        const r = await client.call("eth_getTransactionReceipt", [
-          hash
-        ]);
-        return [t, r];
+        return t;
       });
       if (isJSONMode()) {
-        printJSON({ transaction: tx, receipt });
+        printJSON(tx);
         return;
       }
       const network = resolveNetwork(program2);
@@ -277,20 +306,13 @@ Examples:
         const formatted = formatHexWithRaw(tx.blockNumber);
         pairs.push(["Block", formatted ?? String(tx.blockNumber)]);
       }
-      if (receipt) {
-        if (receipt.status === "0x1") {
-          pairs.push(["Status", `${successBadge()} Success`]);
-        } else if (receipt.status) {
-          pairs.push(["Status", `${failBadge()} Failed`]);
-        }
-        if (receipt.gasUsed) {
-          const formatted = formatHexWithRaw(receipt.gasUsed);
-          pairs.push(["Gas Used", formatted ?? String(receipt.gasUsed)]);
-        }
-        if (receipt.effectiveGasPrice) {
-          const formatted = formatGweiWithRaw(receipt.effectiveGasPrice);
-          pairs.push(["Gas Price", formatted ?? String(receipt.effectiveGasPrice)]);
-        }
+      if (tx.nonce) {
+        const formatted = formatHexWithRaw(tx.nonce);
+        pairs.push(["Nonce", formatted ?? String(tx.nonce)]);
+      }
+      if (tx.gasPrice) {
+        const formatted = formatGweiWithRaw(tx.gasPrice);
+        pairs.push(["Gas Price", formatted ?? String(tx.gasPrice)]);
       }
       const explorerURL = etherscanTxURL(hash, network);
       if (explorerURL) {
@@ -299,7 +321,7 @@ Examples:
       printKeyValueBox(pairs);
       if (verbose) {
         console.log("");
-        printJSON({ transaction: tx, receipt });
+        printJSON(tx);
       }
     } catch (err) {
       exitWithError(err);
@@ -314,7 +336,9 @@ function registerReceipt(program2) {
     `
 Examples:
   alchemy receipt 0xabc123...
-  echo 0xabc123... | alchemy receipt`
+  echo 0xabc123... | alchemy receipt
+
+Tip: use 'alchemy tx <hash>' for transaction details (value, block, nonce). Receipt provides execution results (status, gas used, logs).`
   ).action(async (hashArg) => {
     try {
       const hash = hashArg ?? await readStdinArg("hash");
@@ -598,11 +622,13 @@ async function promptTokensPagination() {
   if (action === null) return "stop";
   return action;
 }
-function formatTokenRows(balances) {
-  const nonZero = balances.filter(
+function filterNonZero(balances) {
+  return balances.filter(
     (tb) => tb.tokenBalance !== "0x0" && tb.tokenBalance !== "0x0000000000000000000000000000000000000000000000000000000000000000"
   );
-  return nonZero.map((tb) => {
+}
+function formatTokenRows(balances) {
+  return filterNonZero(balances).map((tb) => {
     let decimalBalance = dim("unparseable");
     try {
       decimalBalance = BigInt(tb.tokenBalance).toString();
@@ -611,15 +637,72 @@ function formatTokenRows(balances) {
     return [tb.contractAddress, decimalBalance, tb.tokenBalance];
   });
 }
+function formatWithDecimals(rawBalance, decimals) {
+  if (decimals === null || decimals === 0) {
+    try {
+      return BigInt(rawBalance).toString();
+    } catch {
+      return rawBalance;
+    }
+  }
+  try {
+    const raw = BigInt(rawBalance);
+    const divisor = 10n ** BigInt(decimals);
+    const whole = raw / divisor;
+    const remainder = raw % divisor;
+    if (remainder === 0n) return whole.toString();
+    const fracStr = remainder.toString().padStart(decimals, "0").replace(/0+$/, "");
+    return `${whole}.${fracStr}`;
+  } catch {
+    return rawBalance;
+  }
+}
+async function resolveMetadata(client, balances) {
+  const nonZero = filterNonZero(balances);
+  const results = await Promise.all(
+    nonZero.map(async (tb) => {
+      try {
+        const meta = await client.call("alchemy_getTokenMetadata", [tb.contractAddress]);
+        return [tb.contractAddress, meta];
+      } catch {
+        return [tb.contractAddress, { name: null, symbol: null, decimals: null, logo: null }];
+      }
+    })
+  );
+  return new Map(results);
+}
+function formatResolvedRows(balances, metadata) {
+  return filterNonZero(balances).map((tb) => {
+    const meta = metadata.get(tb.contractAddress);
+    const symbol = meta?.symbol ?? "???";
+    const formatted = formatWithDecimals(tb.tokenBalance, meta?.decimals ?? null);
+    return [tb.contractAddress, symbol, `${formatted} ${symbol}`];
+  });
+}
+function formatResolvedJSON(balances, metadata) {
+  return filterNonZero(balances).map((tb) => {
+    const meta = metadata.get(tb.contractAddress);
+    return {
+      contractAddress: tb.contractAddress,
+      tokenBalance: tb.tokenBalance,
+      ...meta?.symbol && { symbol: meta.symbol },
+      ...meta?.name && { name: meta.name },
+      ...meta?.decimals !== null && meta?.decimals !== void 0 && { decimals: meta.decimals },
+      ...meta?.decimals !== null && meta?.decimals !== void 0 && {
+        formattedBalance: formatWithDecimals(tb.tokenBalance, meta.decimals)
+      }
+    };
+  });
+}
 function registerTokens(program2) {
-  const cmd = program2.command("tokens").description("Token API wrappers").argument("[address]", "Wallet address or ENS name (default action: list balances)").option("--page-key <key>", "Pagination key from a previous response").addHelpText(
+  const cmd = program2.command("tokens").description("Token API wrappers");
+  cmd.command("balances").argument("[address]", "Wallet address or ENS name, or pipe via stdin").description("Get ERC-20 token balances for an address").option("--page-key <key>", "Pagination key from a previous response").option("--metadata", "Fetch token metadata (symbol, decimals) and show formatted balances").addHelpText(
     "after",
     `
 Examples:
-  alchemy tokens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
-  alchemy tokens metadata 0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48
-  alchemy tokens allowance --owner 0x... --spender 0x... --contract 0x...
-  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy tokens`
+  alchemy tokens balances 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+  alchemy tokens balances 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --metadata
+  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy tokens balances`
   ).action(async (addressArg, opts) => {
     try {
       const addressInput = addressArg ?? await readStdinArg("address");
@@ -634,24 +717,50 @@ Examples:
         "Token balances fetched",
         () => client.call("alchemy_getTokenBalances", params)
       );
-      if (isJSONMode()) {
-        printJSON(result);
+      const nonZero = filterNonZero(result.tokenBalances);
+      if (nonZero.length === 0) {
+        if (isJSONMode()) {
+          printJSON(result);
+        } else {
+          emptyState("No token balances found.");
+        }
         return;
       }
-      const rows = formatTokenRows(result.tokenBalances);
-      if (rows.length === 0) {
-        emptyState("No token balances found.");
+      const metadata = opts.metadata ? await withSpinner(
+        `Resolving metadata for ${nonZero.length} tokens\u2026`,
+        "Metadata resolved",
+        () => resolveMetadata(client, result.tokenBalances)
+      ) : null;
+      if (isJSONMode()) {
+        if (metadata) {
+          printJSON({
+            address: result.address,
+            tokenBalances: formatResolvedJSON(result.tokenBalances, metadata),
+            ...result.pageKey && { pageKey: result.pageKey }
+          });
+        } else {
+          printJSON(result);
+        }
         return;
       }
-      let totalShown = rows.length;
+      let totalShown = nonZero.length;
       printKeyValueBox([
         ["Address", address],
         ["Network", client.network],
         ["Tokens", String(totalShown)]
       ]);
-      printTable(["Contract", "Balance (base units)", "Raw (hex)"], rows);
+      if (metadata) {
+        const rows = formatResolvedRows(result.tokenBalances, metadata);
+        printTable(["Contract", "Symbol", "Balance"], rows);
+      } else {
+        const rows = formatTokenRows(result.tokenBalances);
+        printTable(["Contract", "Balance (base units)", "Raw (hex)"], rows);
+      }
       console.log(`
   ${dim(`${totalShown} tokens (zero balances hidden).`)}`);
+      if (!metadata) {
+        console.log(`  ${dim("Tip: use --metadata to fetch token symbols, decimals, and show formatted balances.")}`);
+      }
       if (verbose) {
         console.log("");
         printJSON(result);
@@ -674,10 +783,21 @@ Examples:
           printJSON(nextResult);
           return;
         }
-        const nextRows = formatTokenRows(nextResult.tokenBalances);
-        totalShown += nextRows.length;
-        if (nextRows.length > 0) {
-          printTable(["Contract", "Balance (base units)", "Raw (hex)"], nextRows);
+        const nextNonZero = filterNonZero(nextResult.tokenBalances);
+        totalShown += nextNonZero.length;
+        if (nextNonZero.length > 0) {
+          if (metadata) {
+            const nextMeta = await withSpinner(
+              `Resolving metadata for ${nextNonZero.length} tokens\u2026`,
+              "Metadata resolved",
+              () => resolveMetadata(client, nextResult.tokenBalances)
+            );
+            const rows = formatResolvedRows(nextResult.tokenBalances, nextMeta);
+            printTable(["Contract", "Symbol", "Balance"], rows);
+          } else {
+            const rows = formatTokenRows(nextResult.tokenBalances);
+            printTable(["Contract", "Balance (base units)", "Raw (hex)"], rows);
+          }
         }
         console.log(`
   ${dim(`${totalShown} tokens total (zero balances hidden).`)}`);
@@ -691,7 +811,12 @@ Examples:
       exitWithError(err);
     }
   });
-  cmd.command("metadata <contract>").description("Get ERC-20 token metadata").action(async (contract) => {
+  cmd.command("metadata <contract>").description("Get ERC-20 token metadata (name, symbol, decimals, logo)").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy tokens metadata 0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48`
+  ).action(async (contract) => {
     try {
       validateAddress(contract);
       const client = clientFromFlags(program2);
@@ -715,11 +840,11 @@ Examples:
       const result = await withSpinner(
         "Fetching token allowance\u2026",
         "Token allowance fetched",
-        () => client.call("alchemy_getTokenAllowance", [
-          opts.owner,
-          opts.spender,
-          opts.contract
-        ])
+        () => client.call("alchemy_getTokenAllowance", [{
+          owner: opts.owner,
+          spender: opts.spender,
+          contract: opts.contract
+        }])
       );
       if (isJSONMode()) printJSON(result);
       else printSyntaxJSON(result);
@@ -732,34 +857,22 @@ Examples:
 // src/commands/network.ts
 function registerNetwork(program2) {
   const cmd = program2.command("network").description("Manage networks");
-  cmd.command("list").description("List RPC network IDs for use with --network (e.g. eth-mainnet)").option(
-    "--configured",
-    "List only configured app RPC networks (requires access key and app context)"
-  ).option(
-    "--app-id <id>",
-    "App ID for configured network lookups (overrides saved app)"
-  ).action(async (opts) => {
+  cmd.command("list").description("List RPC network IDs for use with --network (e.g. eth-mainnet)").option("--mainnet-only", "Show only mainnet networks").option("--testnet-only", "Show only testnet networks").option("--search <term>", "Filter networks by name or ID").action(async (opts) => {
     try {
-      const supported = getRPCNetworks();
+      let display = getRPCNetworks();
       const current = resolveNetwork(program2);
-      const configured = opts.configured ? await withSpinner(
-        "Fetching configured networks\u2026",
-        "Configured networks fetched",
-        () => resolveConfiguredNetworkSlugs(program2, opts.appId)
-      ) : null;
-      const configuredSet = new Set(configured ?? []);
-      const appId = opts.configured ? opts.appId || resolveAppId(program2) : void 0;
-      const display = configured ? supported.filter((network) => configuredSet.has(network.id)) : supported;
+      if (opts.mainnetOnly) {
+        display = display.filter((n) => !n.isTestnet);
+      } else if (opts.testnetOnly) {
+        display = display.filter((n) => n.isTestnet);
+      }
+      if (opts.search) {
+        const term = opts.search.toLowerCase();
+        display = display.filter(
+          (n) => n.id.toLowerCase().includes(term) || n.name.toLowerCase().includes(term) || n.family.toLowerCase().includes(term)
+        );
+      }
       if (isJSONMode()) {
-        if (configured) {
-          printJSON({
-            mode: "configured",
-            appId,
-            configuredNetworkIds: configured,
-            networks: display
-          });
-          return;
-        }
         printJSON(display);
         return;
       }
@@ -771,23 +884,18 @@ function registerNetwork(program2) {
         return [idCell, nameCell, network.family, testnetCell];
       });
       printTable(["Network ID", "Name", "Family", "Testnet"], rows);
-      if (configured) {
-        console.log(
-          `
-  ${dim(`Configured networks for app ${appId}: ${display.length}`)}`
-        );
-      }
       console.log(`
   Current: ${green(current)}`);
       console.log(
         `  ${dim("Need Admin API chain identifiers (e.g. ETH_MAINNET)? See: apps chains")}`
       );
+      console.log(
+        `  ${dim("Need configured networks for an app? See: apps networks")}`
+      );
       if (verbose) {
         console.log("");
         printJSON({
-          mode: configured ? "configured" : "all",
-          appId: appId ?? null,
-          configuredNetworkIds: configured ?? null,
+          mode: "all",
           networks: display,
           currentNetwork: current
         });
@@ -1182,6 +1290,95 @@ function registerApps(program2) {
       exitWithError(err);
     }
   });
+  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 appId = opts.appId || resolveAppId(program2);
+      if (!appId) throw errAppRequired();
+      const app = await withSpinner(
+        "Fetching app\u2026",
+        "App fetched",
+        () => admin.getApp(appId)
+      );
+      const slugs = app.chainNetworks.map((n) => {
+        const match = n.rpcUrl?.match(/^https:\/\/([^.]+)\.g\.alchemy\.com(?:\/|$)/);
+        return match ? match[1] : null;
+      }).filter((s) => Boolean(s));
+      const uniqueSlugs = Array.from(new Set(slugs)).sort();
+      if (isJSONMode()) {
+        printJSON({ appId: app.id, appName: app.name, networks: uniqueSlugs });
+        return;
+      }
+      if (uniqueSlugs.length === 0) {
+        emptyState(`No RPC networks configured for ${app.name}.`);
+        return;
+      }
+      const rows = uniqueSlugs.map((slug) => [slug]);
+      printTable(["Network ID"], rows);
+      console.log(`
+  ${dim(`${uniqueSlugs.length} networks configured for ${app.name} (${app.id})`)}`);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("select [id]").description("Select an app to use as the default").action(async (id) => {
+    try {
+      const admin = adminClientFromFlags(program2);
+      let selected;
+      if (id) {
+        selected = await withSpinner(
+          "Fetching app\u2026",
+          "App fetched",
+          () => admin.getApp(id)
+        );
+      } else {
+        const result = await withSpinner(
+          "Fetching apps\u2026",
+          "Apps fetched",
+          () => admin.listAllApps()
+        );
+        if (result.apps.length === 0) {
+          emptyState("No apps found.");
+          return;
+        }
+        if (isJSONMode()) {
+          printJSON({ apps: result.apps.map(maskAppSecrets) });
+          return;
+        }
+        const appId = await promptSelect({
+          message: "Select an app",
+          options: result.apps.map((app) => ({
+            value: app.id,
+            label: app.name,
+            hint: `${app.chainNetworks.length} networks`
+          })),
+          cancelMessage: "Cancelled app selection."
+        });
+        if (!appId) return;
+        const found = result.apps.find((a) => a.id === appId);
+        if (!found) return;
+        selected = found;
+      }
+      const cfg = load();
+      save({
+        ...cfg,
+        app: {
+          id: selected.id,
+          name: selected.name,
+          apiKey: selected.apiKey,
+          webhookApiKey: selected.webhookApiKey
+        }
+      });
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(selected));
+        return;
+      }
+      console.log(`  ${green("\u2713")} Selected app: ${selected.name}`);
+      console.log(`  ${dim("Saved to config")}`);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
   cmd.command("chains").description("List Admin API chain identifiers for app configuration (e.g. ETH_MAINNET)").action(async () => {
     try {
       const admin = adminClientFromFlags(program2);
@@ -1471,13 +1668,13 @@ async function requestJSON(url, options) {
 }
 async function callApiData(apiKey, path, options = {}) {
   if (!apiKey) throw errAuthRequired();
-  const base = new URL(`https://api.g.alchemy.com/data/v1/${apiKey}/`);
+  const base = new URL(`https://api.g.${getBaseDomain()}/data/v1/${apiKey}/`);
   const url = withQuery(new URL(path.replace(/^\//, ""), base), options.query);
   return requestJSON(url, { ...options, path });
 }
 async function callApiPrices(apiKey, path, options = {}) {
   if (!apiKey) throw errAuthRequired();
-  const base = new URL(`https://api.g.alchemy.com/prices/v1/${apiKey}/`);
+  const base = new URL(`https://api.g.${getBaseDomain()}/prices/v1/${apiKey}/`);
   const url = withQuery(new URL(path.replace(/^\//, ""), base), options.query);
   return requestJSON(url, { ...options, path });
 }
@@ -1487,7 +1684,7 @@ async function callNotify(token, path, options = {}) {
       "Webhook API key required. Set ALCHEMY_WEBHOOK_API_KEY (or ALCHEMY_NOTIFY_AUTH_TOKEN) or pass --webhook-api-key."
     );
   }
-  const base = new URL("https://dashboard.alchemy.com/api/");
+  const base = new URL(`https://dashboard.${getBaseDomain()}/api/`);
   const url = withQuery(new URL(path.replace(/^\//, ""), base), options.query);
   return requestJSON(url, {
     ...options,
@@ -1504,14 +1701,14 @@ function registerPrices(program2) {
   const cmd = program2.command("prices").description("Prices API wrappers");
   cmd.command("symbol <symbols>").description("Get spot prices by symbol (comma-separated)").action(async (symbols) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const values = splitCommaList(symbols);
       const query = new URLSearchParams();
       for (const symbol of values) query.append("symbols", symbol);
+      const x402 = resolveX402Client(program2);
       const result = await withSpinner(
         "Fetching prices\u2026",
         "Prices fetched",
-        () => callApiPrices(apiKey, `/tokens/by-symbol?${query.toString()}`)
+        () => x402 ? x402.callRest(`prices/v1/tokens/by-symbol?${query.toString()}`) : callApiPrices(resolveAPIKey(program2), `/tokens/by-symbol?${query.toString()}`)
       );
       if (isJSONMode()) printJSON(result);
       else printSyntaxJSON(result);
@@ -1521,12 +1718,12 @@ function registerPrices(program2) {
   });
   cmd.command("address").description("Get spot prices by token addresses").requiredOption("--addresses <json>", "JSON array of {network,address}").action(async (opts) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const body = { addresses: JSON.parse(opts.addresses) };
+      const x402 = resolveX402Client(program2);
       const result = await withSpinner(
         "Fetching prices\u2026",
         "Prices fetched",
-        () => callApiPrices(apiKey, "/tokens/by-address", { method: "POST", body })
+        () => x402 ? x402.callRest("prices/v1/tokens/by-address", { method: "POST", body }) : callApiPrices(resolveAPIKey(program2), "/tokens/by-address", { method: "POST", body })
       );
       if (isJSONMode()) printJSON(result);
       else printSyntaxJSON(result);
@@ -1534,14 +1731,20 @@ function registerPrices(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("historical").description("Get historical prices").requiredOption("--body <json>", "JSON request payload").action(async (opts) => {
+  cmd.command("historical").description("Get historical prices").requiredOption("--body <json>", "JSON request payload").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy prices historical --body '{"symbol":"ETH","startTime":"2024-01-01T00:00:00Z","endTime":"2024-01-02T00:00:00Z","interval":"1h"}'
+  alchemy prices historical --body '{"address":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","network":"eth-mainnet","startTime":"2024-06-01","endTime":"2024-06-07","interval":"1d"}'`
+  ).action(async (opts) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const payload = JSON.parse(opts.body);
+      const x402 = resolveX402Client(program2);
       const result = await withSpinner(
         "Fetching historical prices\u2026",
         "Historical prices fetched",
-        () => callApiPrices(apiKey, "/tokens/historical", { method: "POST", body: payload })
+        () => x402 ? x402.callRest("prices/v1/tokens/historical", { method: "POST", body: payload }) : callApiPrices(resolveAPIKey(program2), "/tokens/historical", { method: "POST", body: payload })
       );
       if (isJSONMode()) printJSON(result);
       else printSyntaxJSON(result);
@@ -1552,20 +1755,20 @@ function registerPrices(program2) {
 }
 
 // src/commands/portfolio.ts
-async function runDataCall(apiKey, title, path, body) {
+async function runDataCall(program2, title, path, body) {
+  const x402 = resolveX402Client(program2);
   return withSpinner(
     `Fetching ${title}\u2026`,
     `${title} fetched`,
-    () => callApiData(apiKey, path, { method: "POST", body })
+    () => x402 ? x402.callRest(`data/v1${path}`, { method: "POST", body }) : callApiData(resolveAPIKey(program2), path, { method: "POST", 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) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const result = await runDataCall(
-        apiKey,
+        program2,
         "token portfolio",
         "/assets/tokens/by-address",
         JSON.parse(opts.body)
@@ -1578,9 +1781,8 @@ function registerPortfolio(program2) {
   });
   cmd.command("token-balances").description("Get token balances by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/tokens/balances/by-address").action(async (opts) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const result = await runDataCall(
-        apiKey,
+        program2,
         "token balances",
         "/assets/tokens/balances/by-address",
         JSON.parse(opts.body)
@@ -1593,9 +1795,8 @@ function registerPortfolio(program2) {
   });
   cmd.command("nfts").description("Get NFT portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/by-address").action(async (opts) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const result = await runDataCall(
-        apiKey,
+        program2,
         "NFT portfolio",
         "/assets/nfts/by-address",
         JSON.parse(opts.body)
@@ -1608,9 +1809,8 @@ function registerPortfolio(program2) {
   });
   cmd.command("nft-contracts").description("Get NFT contracts by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/contracts/by-address").action(async (opts) => {
     try {
-      const apiKey = resolveAPIKey(program2);
       const result = await runDataCall(
-        apiKey,
+        program2,
         "NFT contracts",
         "/assets/nfts/contracts/by-address",
         JSON.parse(opts.body)
@@ -1621,21 +1821,6 @@ function registerPortfolio(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("transactions").description("Get transaction history by address/network pairs").requiredOption("--body <json>", "JSON body for /transactions/history/by-address").action(async (opts) => {
-    try {
-      const apiKey = resolveAPIKey(program2);
-      const result = await runDataCall(
-        apiKey,
-        "transaction history",
-        "/transactions/history/by-address",
-        JSON.parse(opts.body)
-      );
-      if (isJSONMode()) printJSON(result);
-      else printSyntaxJSON(result);
-    } catch (err) {
-      exitWithError(err);
-    }
-  });
 }
 
 // src/commands/simulate.ts
@@ -1714,15 +1899,24 @@ function registerWebhooks(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("create").description("Create webhook").requiredOption("--body <json>", "Create webhook JSON payload").action(async (opts) => {
+  cmd.command("create").description("Create webhook").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) {
+        if (isJSONMode()) printJSON({ dryRun: true, action: "create-webhook", payload });
+        else {
+          console.log(`  ${dim("Dry run:")} Would create webhook`);
+          printSyntaxJSON(payload);
+        }
+        return;
+      }
       const token = resolveWebhookApiKey(cmd.opts());
       const result = await withSpinner(
         "Creating webhook\u2026",
         "Webhook created",
         () => callNotify(token, "/create-webhook", {
           method: "POST",
-          body: parseRequiredJSON(opts.body, "--body")
+          body: payload
         })
       );
       if (isJSONMode()) printJSON(result);
@@ -1731,15 +1925,24 @@ function registerWebhooks(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("update").description("Update webhook").requiredOption("--body <json>", "Update webhook JSON payload").action(async (opts) => {
+  cmd.command("update").description("Update webhook").requiredOption("--body <json>", "Update webhook JSON payload").option("--dry-run", "Preview without executing").action(async (opts) => {
     try {
+      const payload = parseRequiredJSON(opts.body, "--body");
+      if (opts.dryRun) {
+        if (isJSONMode()) printJSON({ dryRun: true, action: "update-webhook", payload });
+        else {
+          console.log(`  ${dim("Dry run:")} Would update webhook`);
+          printSyntaxJSON(payload);
+        }
+        return;
+      }
       const token = resolveWebhookApiKey(cmd.opts());
       const result = await withSpinner(
         "Updating webhook\u2026",
         "Webhook updated",
         () => callNotify(token, "/update-webhook", {
           method: "PUT",
-          body: parseRequiredJSON(opts.body, "--body")
+          body: payload
         })
       );
       if (isJSONMode()) printJSON(result);
@@ -1748,8 +1951,13 @@ function registerWebhooks(program2) {
       exitWithError(err);
     }
   });
-  cmd.command("delete <webhookId>").description("Delete webhook").option("-y, --yes", "Skip confirmation prompt").action(async (webhookId, opts) => {
+  cmd.command("delete <webhookId>").description("Delete webhook").option("--dry-run", "Preview without executing").option("-y, --yes", "Skip confirmation prompt").action(async (webhookId, opts) => {
     try {
+      if (opts.dryRun) {
+        if (isJSONMode()) printJSON({ dryRun: true, action: "delete-webhook", payload: { webhookId } });
+        else console.log(`  ${dim("Dry run:")} Would delete webhook ${webhookId}`);
+        return;
+      }
       if (!opts.yes && isInteractiveAllowed(program2)) {
         const proceed = await promptConfirm({
           message: `Delete webhook ${webhookId}?`,
@@ -2413,8 +2621,12 @@ function formatAsSystemPrompt(payload) {
   return lines.join("\n");
 }
 function registerAgentPrompt(program2) {
-  program2.command("agent-prompt").description("Emit complete agent/automation usage instructions").action(() => {
+  program2.command("agent-prompt").description("Emit complete agent/automation usage instructions").option("--commands <list>", "Filter to specific commands in JSON output (requires --json). Comma-separated (e.g. balance,tokens,gas)").action((opts) => {
     const payload = buildAgentPrompt(program2);
+    if (opts.commands) {
+      const filter = new Set(opts.commands.split(",").map((s) => s.trim().toLowerCase()));
+      payload.commands = payload.commands.filter((cmd) => filter.has(cmd.name.toLowerCase()));
+    }
     printHuman(formatAsSystemPrompt(payload), payload);
   });
 }
@@ -2477,7 +2689,7 @@ var ROOT_COMMAND_PILLARS = [
   },
   {
     label: "Admin",
-    commands: ["apps", "config", "setup", "completions", "agent-prompt", "update-check", "version", "help"]
+    commands: ["apps", "auth", "config", "setup", "completions", "agent-prompt", "update-check", "version", "help"]
   }
 ];
 function formatCommandSignature(sub) {
@@ -2526,10 +2738,10 @@ 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.3.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(
+).version("0.5.0", "-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 (TTY only)").option("--timeout <ms>", "Request timeout in milliseconds", parseInt).option("--debug", "Enable debug diagnostics").option("--no-interactive", "Disable REPL and prompt-driven interactions").addHelpCommand(false).allowExcessArguments(true).exitOverride((err) => {
+).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) => {
   if (err.code === "commander.help" || err.code === "commander.helpDisplayed" || err.code === "commander.version") {
     process.exit(0);
   }
@@ -2706,7 +2918,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-XNAWN5BR.js");
+      const { runOnboarding } = await import("./onboarding-F5PZMFZU.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -2718,7 +2930,7 @@ ${styledLine}`;
       latestForInteractiveStartup = getAvailableUpdateOnce();
       updateShownDuringInteractiveStartup = Boolean(latestForInteractiveStartup);
     }
-    const { startREPL } = await import("./interactive-CLPT5QDZ.js");
+    const { startREPL } = await import("./interactive-K7XOS6U6.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {
@@ -2750,6 +2962,7 @@ registerGasManager(program);
 registerWebhooks(program);
 registerNetwork(program);
 registerApps(program);
+registerAuth(program);
 registerSetup(program);
 registerConfig(program);
 registerSolana(program);