@alchemy/cli 0.3.1 → 0.4.0

package/dist/{chunk-J6RZM4CJ.js → chunk-PIWNNNMZ.js}

@@ -10,7 +10,6 @@ import {
   errAccessDenied,
   errAccessKeyRequired,
   errAdminAPI,
-  errAppRequired,
   errAuthRequired,
   errInvalidAPIKey,
   errInvalidAccessKey,
@@ -43,7 +42,7 @@ import {
   verbose,
   withSpinner,
   yellow
-} from "./chunk-6XTLILDF.js";
+} from "./chunk-TH75DFAY.js";
 
 // src/lib/client-utils.ts
 function isLocalhost(hostname) {
@@ -383,6 +382,21 @@ async function readStdinArg(name) {
   }
   return data;
 }
+async function readStdinLines(name) {
+  if (process.stdin.isTTY) {
+    throw errInvalidArgs(`Missing <${name}>. Provide it as an argument or pipe via stdin.`);
+  }
+  process.stdin.setEncoding("utf-8");
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  const lines = input.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0) {
+    throw errInvalidArgs(`No <${name}> received on stdin.`);
+  }
+  return lines;
+}
 function validateAddress(address) {
   if (!ADDRESS_RE.test(address)) {
     throw errInvalidArgs(
@@ -1201,26 +1215,6 @@ function clientFromFlags(program, opts) {
   if (!apiKey) throw errAuthRequired();
   return new Client(apiKey, network);
 }
-function appNetworkToSlug(rpcUrl) {
-  let parsed;
-  try {
-    parsed = new URL(rpcUrl);
-  } catch {
-    return null;
-  }
-  const suffix = ".g.alchemy.com";
-  if (!parsed.hostname.endsWith(suffix)) return null;
-  const slug = parsed.hostname.slice(0, -suffix.length);
-  return slug || null;
-}
-async function resolveConfiguredNetworkSlugs(program, appIdOverride) {
-  const appId = appIdOverride || resolveAppId(program);
-  if (!appId) throw errAppRequired();
-  const admin = 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));
-}
 
 // src/commands/wallet.ts
 var WALLET_KEYS_DIR = "wallet-keys";
@@ -1316,6 +1310,7 @@ export {
   AdminClient,
   splitCommaList,
   readStdinArg,
+  readStdinLines,
   validateAddress,
   resolveAddress,
   validateTxHash,
@@ -1326,7 +1321,6 @@ export {
   resolveAppId,
   adminClientFromFlags,
   clientFromFlags,
-  resolveConfiguredNetworkSlugs,
   generateAndPersistWallet,
   importAndPersistWallet,
   registerWallet

package/dist/{chunk-6XTLILDF.js → chunk-TH75DFAY.js}

@@ -198,7 +198,7 @@ function setFlags(opts) {
   timeout = opts.timeout;
 }
 function isRevealMode() {
-  return reveal && Boolean(process.stdout.isTTY);
+  return reveal;
 }
 function isJSONMode() {
   if (forceJSON) return true;
@@ -1114,7 +1114,7 @@ function semverLT(a, b) {
   return false;
 }
 function currentVersion() {
-  return true ? "0.3.1" : "0.0.0";
+  return true ? "0.4.0" : "0.0.0";
 }
 function toUpdateStatus(latestVersion, checkedAt) {
   const current = currentVersion();

package/dist/{chunk-QDDJ3OYO.js → chunk-Z3LXQFIY.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isInteractiveAllowed
-} from "./chunk-6XTLILDF.js";
+} from "./chunk-TH75DFAY.js";
 
 // src/lib/networks.ts
 var TESTNET_TOKEN_RE = /(testnet|sepolia|holesky|hoodi|devnet|minato|amoy|fuji|saigon|cardona|aeneid|curtis|chiado|cassiopeia|blaze|ropsten|signet|mocha|fam|bepolia)$/i;

package/dist/index.js

@@ -5,24 +5,24 @@ import {
   clientFromFlags,
   fetchWithTimeout,
   readStdinArg,
+  readStdinLines,
   registerConfig,
   registerWallet,
   resolveAPIKey,
   resolveAddress,
   resolveAppId,
-  resolveConfiguredNetworkSlugs,
   resolveNetwork,
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-J6RZM4CJ.js";
+} from "./chunk-PIWNNNMZ.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   nativeTokenSymbol,
   shouldRunOnboarding
-} from "./chunk-QDDJ3OYO.js";
+} from "./chunk-Z3LXQFIY.js";
 import {
   EXIT_CODES,
   ErrorCode,
@@ -32,6 +32,7 @@ import {
   debug,
   dim,
   emptyState,
+  errAppRequired,
   errAuthRequired,
   errInvalidAPIKey,
   errInvalidArgs,
@@ -70,7 +71,7 @@ import {
   verbose,
   weiToEth,
   withSpinner
-} from "./chunk-6XTLILDF.js";
+} from "./chunk-TH75DFAY.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -108,6 +109,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 +166,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 +258,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 +295,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 +310,7 @@ Examples:
       printKeyValueBox(pairs);
       if (verbose) {
         console.log("");
-        printJSON({ transaction: tx, receipt });
+        printJSON(tx);
       }
     } catch (err) {
       exitWithError(err);
@@ -314,7 +325,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 +611,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 +626,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 +706,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 +772,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 +800,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);
@@ -732,34 +846,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 +873,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 +1279,37 @@ 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("chains").description("List Admin API chain identifiers for app configuration (e.g. ETH_MAINNET)").action(async () => {
     try {
       const admin = adminClientFromFlags(program2);
@@ -1534,7 +1662,13 @@ 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);
@@ -1621,21 +1755,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 +1833,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 +1859,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 +1885,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 +2555,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);
   });
 }
@@ -2526,10 +2672,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.4.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 +2852,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-XNAWN5BR.js");
+      const { runOnboarding } = await import("./onboarding-WQ2TWDM3.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -2718,7 +2864,7 @@ ${styledLine}`;
       latestForInteractiveStartup = getAvailableUpdateOnce();
       updateShownDuringInteractiveStartup = Boolean(latestForInteractiveStartup);
     }
-    const { startREPL } = await import("./interactive-CLPT5QDZ.js");
+    const { startREPL } = await import("./interactive-NASSNJHQ.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {

package/dist/{interactive-CLPT5QDZ.js → interactive-NASSNJHQ.js}

@@ -3,7 +3,7 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getRPCNetworkIds,
   getSetupMethod
-} from "./chunk-QDDJ3OYO.js";
+} from "./chunk-Z3LXQFIY.js";
 import {
   bgRgb,
   bold,
@@ -19,7 +19,7 @@ import {
   rgb,
   setBrandedHelpSuppressed,
   setReplMode
-} from "./chunk-6XTLILDF.js";
+} from "./chunk-TH75DFAY.js";
 
 // src/commands/interactive.ts
 import * as readline from "readline";

package/dist/{onboarding-XNAWN5BR.js → onboarding-WQ2TWDM3.js}

@@ -5,7 +5,7 @@ import {
   generateAndPersistWallet,
   importAndPersistWallet,
   selectOrCreateApp
-} from "./chunk-J6RZM4CJ.js";
+} from "./chunk-PIWNNNMZ.js";
 import {
   bold,
   brand,
@@ -19,7 +19,7 @@ import {
   promptSelect,
   promptText,
   save
-} from "./chunk-6XTLILDF.js";
+} from "./chunk-TH75DFAY.js";
 
 // src/commands/onboarding.ts
 function printNextSteps(method) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Alchemy CLI — interact with blockchain data",
   "type": "module",
   "bin": {