@alchemy/cli 0.2.1 → 0.3.0

package/dist/index.js

@@ -8,19 +8,21 @@ import {
   registerConfig,
   registerWallet,
   resolveAPIKey,
+  resolveAddress,
   resolveAppId,
   resolveConfiguredNetworkSlugs,
   resolveNetwork,
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-XP5KF4W2.js";
+} from "./chunk-UPQTWEPP.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
+  nativeTokenSymbol,
   shouldRunOnboarding
-} from "./chunk-HBRTTBCY.js";
+} from "./chunk-VYQ5V2ZR.js";
 import {
   EXIT_CODES,
   ErrorCode,
@@ -59,20 +61,21 @@ import {
   printUpdateNotice,
   promptSelect,
   quiet,
+  red,
   setFlags,
   successBadge,
   timeAgo,
   verbose,
   weiToEth,
   withSpinner
-} from "./chunk-SDUCDSCZ.js";
+} from "./chunk-MF6DXNO7.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
 
 // src/commands/rpc.ts
 function registerRPC(program2) {
-  program2.command("rpc <method> [params...]").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("Make a raw JSON-RPC call").addHelpText(
     "after",
     `
 Examples:
@@ -104,36 +107,50 @@ Examples:
 
 // src/commands/balance.ts
 function registerBalance(program2) {
-  program2.command("balance [address]").alias("bal").description("Get the ETH balance of an address").addHelpText(
+  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",
     `
 Examples:
   alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
   alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n polygon-mainnet
-  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy balance`
-  ).action(async (addressArg) => {
+  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy balance
+  alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --block 15537393
+  alchemy balance vitalik.eth`
+  ).option("--block <block>", "Block number, hex, or tag (default: latest)").action(async (addressArg, opts) => {
     try {
-      const address = addressArg ?? await readStdinArg("address");
-      validateAddress(address);
+      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 result = await withSpinner(
         "Fetching balance\u2026",
         "Balance fetched",
-        () => client.call("eth_getBalance", [address, "latest"])
+        () => 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(),
-          eth: weiToEth(wei),
+          balance: weiToEth(wei),
+          symbol,
           network
         });
       } else {
         printKeyValueBox([
           ["Address", address],
-          ["Balance", green(weiToEth(wei) + " ETH")],
+          ["Balance", green(`${weiToEth(wei)} ${symbol}`)],
           ["Network", network]
         ]);
         if (verbose) {
@@ -151,9 +168,76 @@ Examples:
   });
 }
 
+// src/lib/block-format.ts
+function parseHexQuantity(value) {
+  if (typeof value !== "string" || !/^0x[0-9a-f]+$/i.test(value)) {
+    return void 0;
+  }
+  try {
+    return BigInt(value);
+  } catch {
+    return void 0;
+  }
+}
+function formatWithCommas(value) {
+  return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function formatHexQuantity(value) {
+  const parsed = parseHexQuantity(value);
+  if (parsed === void 0) return void 0;
+  return formatWithCommas(parsed);
+}
+function formatBlockTimestamp(value) {
+  if (typeof value !== "string") return void 0;
+  const parsed = parseHexQuantity(value);
+  if (parsed === void 0) return void 0;
+  const millis = Number(parsed) * 1e3;
+  if (!Number.isFinite(millis)) return void 0;
+  const d = new Date(millis);
+  if (Number.isNaN(d.getTime())) return void 0;
+  const iso = d.toISOString().replace(".000Z", "Z");
+  return `${iso} ${dim("(" + timeAgo(value) + ")")}`;
+}
+function formatHexWithRaw(value) {
+  if (typeof value !== "string") return void 0;
+  const parsed = parseHexQuantity(value);
+  if (parsed === void 0) return void 0;
+  return `${formatWithCommas(parsed)} ${dim(`(${value})`)}`;
+}
+function formatWeiWithRaw(value, symbol = "ETH") {
+  if (typeof value !== "string") return void 0;
+  const parsed = parseHexQuantity(value);
+  if (parsed === void 0) return void 0;
+  return `${weiToEth(parsed)} ${symbol} ${dim(`(${value})`)}`;
+}
+function formatGwei(gwei) {
+  const fixed = gwei.toFixed(9);
+  return fixed.replace(/\.?0+$/, "") || "0";
+}
+function formatGweiWithRaw(value) {
+  if (typeof value !== "string") return void 0;
+  const parsed = parseHexQuantity(value);
+  if (parsed === void 0) return void 0;
+  const gwei = Number(parsed) / 1e9;
+  return `${formatGwei(gwei)} gwei ${dim(`(${value})`)}`;
+}
+function formatGasSummary(gasUsed, gasLimit, options) {
+  const used = parseHexQuantity(gasUsed);
+  const limit = parseHexQuantity(gasLimit);
+  if (used === void 0 || limit === void 0) return void 0;
+  const usedFormatted = formatWithCommas(used);
+  const limitFormatted = formatWithCommas(limit);
+  if (limit === 0n) return `${usedFormatted} / ${limitFormatted}`;
+  const bps = used * 10000n / limit;
+  const percent = Number(bps) / 100;
+  const percentText = `${percent.toFixed(2)}%`;
+  const percentDisplay = options?.colored ? dim(percentText) : percentText;
+  return `${usedFormatted} / ${limitFormatted} (${percentDisplay})`;
+}
+
 // src/commands/tx.ts
 function registerTx(program2) {
-  program2.command("tx [hash]").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").addHelpText(
     "after",
     `
 Examples:
@@ -178,23 +262,34 @@ Examples:
         printJSON({ transaction: tx, receipt });
         return;
       }
+      const network = resolveNetwork(program2);
+      const symbol = nativeTokenSymbol(network);
       const pairs = [["Hash", hash]];
       if (tx.from) pairs.push(["From", String(tx.from)]);
       if (tx.to) pairs.push(["To", String(tx.to)]);
       if (tx.value) {
-        const wei = BigInt(tx.value);
-        pairs.push(["Value", green(weiToEth(wei) + " ETH")]);
+        const formatted = formatWeiWithRaw(tx.value, symbol);
+        pairs.push(["Value", formatted ? green(formatted) : String(tx.value)]);
+      }
+      if (tx.blockNumber) {
+        const formatted = formatHexWithRaw(tx.blockNumber);
+        pairs.push(["Block", formatted ?? String(tx.blockNumber)]);
       }
-      if (tx.blockNumber) pairs.push(["Block", 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) pairs.push(["Gas Used", String(receipt.gasUsed)]);
+        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)]);
+        }
       }
-      const network = resolveNetwork(program2);
       const explorerURL = etherscanTxURL(hash, network);
       if (explorerURL) {
         pairs.push(["Explorer", explorerURL]);
@@ -210,53 +305,74 @@ Examples:
   });
 }
 
-// src/lib/block-format.ts
-function parseHexQuantity(value) {
-  if (typeof value !== "string" || !/^0x[0-9a-f]+$/i.test(value)) {
-    return void 0;
-  }
-  try {
-    return BigInt(value);
-  } catch {
-    return void 0;
-  }
-}
-function formatWithCommas(value) {
-  return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-}
-function formatHexQuantity(value) {
-  const parsed = parseHexQuantity(value);
-  if (parsed === void 0) return void 0;
-  return formatWithCommas(parsed);
-}
-function formatBlockTimestamp(value) {
-  if (typeof value !== "string") return void 0;
-  const parsed = parseHexQuantity(value);
-  if (parsed === void 0) return void 0;
-  const millis = Number(parsed) * 1e3;
-  if (!Number.isFinite(millis)) return void 0;
-  const d = new Date(millis);
-  if (Number.isNaN(d.getTime())) return void 0;
-  const iso = d.toISOString().replace(".000Z", "Z");
-  return `${iso} ${dim("(" + timeAgo(value) + ")")}`;
-}
-function formatGasSummary(gasUsed, gasLimit, options) {
-  const used = parseHexQuantity(gasUsed);
-  const limit = parseHexQuantity(gasLimit);
-  if (used === void 0 || limit === void 0) return void 0;
-  const usedFormatted = formatWithCommas(used);
-  const limitFormatted = formatWithCommas(limit);
-  if (limit === 0n) return `${usedFormatted} / ${limitFormatted}`;
-  const bps = used * 10000n / limit;
-  const percent = Number(bps) / 100;
-  const percentText = `${percent.toFixed(2)}%`;
-  const percentDisplay = options?.colored ? dim(percentText) : percentText;
-  return `${usedFormatted} / ${limitFormatted} (${percentDisplay})`;
+// src/commands/receipt.ts
+function registerReceipt(program2) {
+  program2.command("receipt").argument("[hash]", "Transaction hash (0x...) or pipe via stdin").description("Get transaction receipt (status, gas used, logs)").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy receipt 0xabc123...
+  echo 0xabc123... | alchemy receipt`
+  ).action(async (hashArg) => {
+    try {
+      const hash = hashArg ?? await readStdinArg("hash");
+      validateTxHash(hash);
+      const client = clientFromFlags(program2);
+      const receipt = await withSpinner(
+        "Fetching receipt\u2026",
+        "Receipt fetched",
+        () => client.call("eth_getTransactionReceipt", [hash])
+      );
+      if (!receipt) throw errNotFound(`receipt for ${hash}`);
+      if (isJSONMode()) {
+        printJSON(receipt);
+        return;
+      }
+      const pairs = [["Hash", hash]];
+      if (receipt.status === "0x1") {
+        pairs.push(["Status", `${successBadge()} ${green("Success")}`]);
+      } else if (receipt.status) {
+        pairs.push(["Status", `${failBadge()} ${red("Failed")}`]);
+      }
+      if (receipt.from) pairs.push(["From", String(receipt.from)]);
+      if (receipt.to) pairs.push(["To", String(receipt.to)]);
+      if (receipt.contractAddress) {
+        pairs.push(["Contract Created", String(receipt.contractAddress)]);
+      }
+      if (receipt.blockNumber) {
+        const hex = String(receipt.blockNumber);
+        const decoded = formatHexQuantity(hex);
+        pairs.push(["Block", decoded ? `${decoded} ${dim(`(${hex})`)}` : hex]);
+      }
+      if (receipt.gasUsed) {
+        const hex = String(receipt.gasUsed);
+        const decoded = formatHexQuantity(hex);
+        pairs.push(["Gas Used", decoded ? `${decoded} ${dim(`(${hex})`)}` : hex]);
+      }
+      if (receipt.effectiveGasPrice) {
+        const hex = String(receipt.effectiveGasPrice);
+        const wei = BigInt(hex);
+        const gwei = Number(wei) / 1e9;
+        pairs.push(["Gas Price", `${formatGwei(gwei)} gwei ${dim(`(${hex})`)}`]);
+      }
+      if (Array.isArray(receipt.logs)) {
+        pairs.push(["Logs", `${receipt.logs.length} event${receipt.logs.length === 1 ? "" : "s"}`]);
+      }
+      const network = resolveNetwork(program2);
+      const explorerURL = etherscanTxURL(hash, network);
+      if (explorerURL) {
+        pairs.push(["Explorer", explorerURL]);
+      }
+      printKeyValueBox(pairs);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
 }
 
 // src/commands/block.ts
 function registerBlock(program2) {
-  program2.command("block <number>").description("Get block details by number").addHelpText(
+  program2.command("block").argument("<number>", "Block number, hex (0x...), or tag (latest, earliest, pending)").description("Get block details by number").addHelpText(
     "after",
     `
 Examples:
@@ -277,6 +393,9 @@ Examples:
             "block must be a number, hex, or 'latest'"
           );
         }
+        if (num < 0) {
+          throw errInvalidArgs("Block number must be non-negative.");
+        }
         blockParam = `0x${num.toString(16)}`;
       }
       const client = clientFromFlags(program2);
@@ -292,7 +411,7 @@ Examples:
       }
       const pairs = [];
       if (block.number) {
-        const formatted = formatHexQuantity(block.number);
+        const formatted = formatHexWithRaw(block.number);
         pairs.push(["Block", bold(formatted ?? String(block.number))]);
       }
       if (block.hash) pairs.push(["Hash", String(block.hash)]);
@@ -310,11 +429,11 @@ Examples:
         pairs.push(["Gas", gasSummary]);
       } else {
         if (block.gasUsed) {
-          const formatted = formatHexQuantity(block.gasUsed);
+          const formatted = formatHexWithRaw(block.gasUsed);
           pairs.push(["Gas Used", formatted ?? String(block.gasUsed)]);
         }
         if (block.gasLimit) {
-          const formatted = formatHexQuantity(block.gasLimit);
+          const formatted = formatHexWithRaw(block.gasLimit);
           pairs.push(["Gas Limit", formatted ?? String(block.gasLimit)]);
         }
       }
@@ -333,8 +452,28 @@ Examples:
 }
 
 // src/commands/nfts.ts
+async function promptNFTPagination(shown, total) {
+  const action = await promptSelect({
+    message: `Showing ${shown} of ${total} NFTs`,
+    options: [
+      { label: "Load next page", value: "next" },
+      { label: "Stop here", value: "stop" }
+    ],
+    initialValue: "next",
+    cancelMessage: "Stopped pagination."
+  });
+  if (action === null) return "stop";
+  return action;
+}
+function formatNFTRows(nfts) {
+  return nfts.map((nft) => [
+    nft.contract.name || dim("unnamed"),
+    nft.name || `#${nft.tokenId}`,
+    nft.contract.address
+  ]);
+}
 function registerNFTs(program2) {
-  const cmd = program2.command("nfts").description("NFT API wrappers").argument("[address]", "Wallet address (default action: list owned NFTs)").option("--limit <n>", "Maximum number of NFTs to return", parseInt).option("--page-key <key>", "Pagination key from a previous response").addHelpText(
+  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(
     "after",
     `
 Examples:
@@ -344,15 +483,15 @@ Examples:
   echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy nfts`
   ).action(async (addressArg, opts) => {
     try {
-      const address = addressArg ?? await readStdinArg("address");
-      validateAddress(address);
+      const addressInput = addressArg ?? await readStdinArg("address");
+      const client = clientFromFlags(program2);
+      const address = await resolveAddress(addressInput, client);
       const params = {
         owner: address,
         withMetadata: "true"
       };
       if (opts.limit) params.pageSize = String(opts.limit);
       if (opts.pageKey) params.pageKey = opts.pageKey;
-      const client = clientFromFlags(program2);
       const result = await withSpinner(
         "Fetching NFTs\u2026",
         "NFTs fetched",
@@ -366,19 +505,41 @@ Examples:
         emptyState("No NFTs found.");
         return;
       }
-      const rows = result.ownedNfts.map((nft) => [
-        nft.contract.name || dim("unnamed"),
-        nft.name || `#${nft.tokenId}`,
-        nft.contract.address
-      ]);
-      printTable(["Collection", "Name", "Contract"], rows);
+      let shown = result.ownedNfts.length;
+      printTable(["Collection", "Name", "Contract"], formatNFTRows(result.ownedNfts));
       if (verbose) {
         console.log("");
         printJSON(result);
       }
-      if (result.pageKey) {
+      const interactive = isInteractiveAllowed(program2);
+      let pageKey = result.pageKey;
+      while (pageKey && interactive) {
+        const action = await promptNFTPagination(shown, result.totalCount);
+        if (action === "stop") {
+          console.log(`
+  ${dim(`Next page key: ${pageKey}`)}`);
+          break;
+        }
+        const nextParams = {
+          owner: address,
+          withMetadata: "true",
+          pageKey
+        };
+        if (opts.limit) nextParams.pageSize = String(opts.limit);
+        const nextResult = await withSpinner(
+          "Fetching next page\u2026",
+          "Page fetched",
+          () => client.callEnhanced("getNFTsForOwner", nextParams)
+        );
+        if (nextResult.ownedNfts.length > 0) {
+          printTable(["Collection", "Name", "Contract"], formatNFTRows(nextResult.ownedNfts));
+          shown += nextResult.ownedNfts.length;
+        }
+        pageKey = nextResult.pageKey;
+      }
+      if (pageKey && !interactive) {
         console.log(`
-  ${dim(`More results available. Use --page-key ${result.pageKey} to see the next page.`)}`);
+  ${dim(`More results available. Use --page-key ${pageKey} to see the next page.`)}`);
       }
     } catch (err) {
       exitWithError(err);
@@ -422,8 +583,34 @@ Examples:
 }
 
 // src/commands/tokens.ts
+async function promptTokensPagination() {
+  const action = await promptSelect({
+    message: "More token balances available",
+    options: [
+      { label: "Load next page", value: "next" },
+      { label: "Stop here", value: "stop" }
+    ],
+    initialValue: "next",
+    cancelMessage: "Stopped pagination."
+  });
+  if (action === null) return "stop";
+  return action;
+}
+function formatTokenRows(balances) {
+  const nonZero = balances.filter(
+    (tb) => tb.tokenBalance !== "0x0" && tb.tokenBalance !== "0x0000000000000000000000000000000000000000000000000000000000000000"
+  );
+  return nonZero.map((tb) => {
+    let decimalBalance = dim("unparseable");
+    try {
+      decimalBalance = BigInt(tb.tokenBalance).toString();
+    } catch {
+    }
+    return [tb.contractAddress, decimalBalance, tb.tokenBalance];
+  });
+}
 function registerTokens(program2) {
-  const cmd = program2.command("tokens").description("Token API wrappers").argument("[address]", "Wallet address (default action: list balances)").option("--page-key <key>", "Pagination key from a previous response").addHelpText(
+  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(
     "after",
     `
 Examples:
@@ -433,13 +620,13 @@ Examples:
   echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy tokens`
   ).action(async (addressArg, opts) => {
     try {
-      const address = addressArg ?? await readStdinArg("address");
-      validateAddress(address);
+      const addressInput = addressArg ?? await readStdinArg("address");
+      const client = clientFromFlags(program2);
+      const address = await resolveAddress(addressInput, client);
       const params = [address];
       if (opts.pageKey) {
         params.push("erc20", { pageKey: opts.pageKey });
       }
-      const client = clientFromFlags(program2);
       const result = await withSpinner(
         "Fetching token balances\u2026",
         "Token balances fetched",
@@ -449,36 +636,54 @@ Examples:
         printJSON(result);
         return;
       }
-      const nonZero = result.tokenBalances.filter(
-        (tb) => tb.tokenBalance !== "0x0" && tb.tokenBalance !== "0x0000000000000000000000000000000000000000000000000000000000000000"
-      );
-      if (nonZero.length === 0) {
+      const rows = formatTokenRows(result.tokenBalances);
+      if (rows.length === 0) {
         emptyState("No token balances found.");
         return;
       }
-      const rows = nonZero.map((tb) => {
-        let decimalBalance = dim("unparseable");
-        try {
-          decimalBalance = BigInt(tb.tokenBalance).toString();
-        } catch {
-        }
-        return [tb.contractAddress, decimalBalance, tb.tokenBalance];
-      });
+      let totalShown = rows.length;
       printKeyValueBox([
         ["Address", address],
         ["Network", client.network],
-        ["Non-zero tokens", String(nonZero.length)]
+        ["Tokens", String(totalShown)]
       ]);
       printTable(["Contract", "Balance (base units)", "Raw (hex)"], rows);
       console.log(`
-  ${dim(`Showing ${nonZero.length} of ${result.tokenBalances.length} contracts (non-zero only).`)}`);
+  ${dim(`${totalShown} tokens (zero balances hidden).`)}`);
       if (verbose) {
         console.log("");
         printJSON(result);
       }
-      if (result.pageKey) {
+      const interactive = isInteractiveAllowed(program2);
+      let pageKey = result.pageKey;
+      while (pageKey && interactive) {
+        const action = await promptTokensPagination();
+        if (action === "stop") {
+          console.log(`
+  ${dim(`Next page key: ${pageKey}`)}`);
+          break;
+        }
+        const nextResult = await withSpinner(
+          "Fetching next page\u2026",
+          "Page fetched",
+          () => client.call("alchemy_getTokenBalances", [address, "erc20", { pageKey }])
+        );
+        if (isJSONMode()) {
+          printJSON(nextResult);
+          return;
+        }
+        const nextRows = formatTokenRows(nextResult.tokenBalances);
+        totalShown += nextRows.length;
+        if (nextRows.length > 0) {
+          printTable(["Contract", "Balance (base units)", "Raw (hex)"], nextRows);
+        }
+        console.log(`
+  ${dim(`${totalShown} tokens total (zero balances hidden).`)}`);
+        pageKey = nextResult.pageKey;
+      }
+      if (pageKey && !interactive) {
         console.log(`
-  ${dim(`More results available. Use --page-key ${result.pageKey} to see the next page.`)}`);
+  ${dim(`More results available. Use --page-key ${pageKey} to see the next page.`)}`);
       }
     } catch (err) {
       exitWithError(err);
@@ -525,7 +730,7 @@ Examples:
 // src/commands/network.ts
 function registerNetwork(program2) {
   const cmd = program2.command("network").description("Manage networks");
-  cmd.command("list").description("List supported RPC network slugs").option(
+  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(
@@ -573,7 +778,7 @@ function registerNetwork(program2) {
       console.log(`
   Current: ${green(current)}`);
       console.log(
-        `  ${dim("Need Admin API chain enums instead? Run: alchemy chains list")}`
+        `  ${dim("Need Admin API chain identifiers (e.g. ETH_MAINNET)? See: apps chains")}`
       );
       if (verbose) {
         console.log("");
@@ -600,43 +805,6 @@ function registerVersion(program2) {
   });
 }
 
-// src/commands/chains.ts
-function registerChains(program2) {
-  const cmd = program2.command("chains").description("Manage Admin API chain enums");
-  cmd.command("list").description("List available Admin API chain enums").action(async () => {
-    try {
-      const admin = adminClientFromFlags(program2);
-      const chains = await withSpinner(
-        "Fetching chains\u2026",
-        "Chains fetched",
-        () => admin.listChains()
-      );
-      if (isJSONMode()) {
-        printJSON(chains);
-        return;
-      }
-      if (chains.length === 0) {
-        emptyState("No chain networks were returned.");
-        return;
-      }
-      const rows = chains.map((c) => [
-        c.id,
-        c.name,
-        c.isTestnet ? dim("yes") : "no",
-        c.availability === "public" ? green(c.availability) : dim(c.availability),
-        c.currency
-      ]);
-      printTable(["ID", "Name", "Testnet", "Availability", "Currency"], rows);
-      if (verbose) {
-        console.log("");
-        printJSON(chains);
-      }
-    } catch (err) {
-      exitWithError(err);
-    }
-  });
-}
-
 // src/commands/apps.ts
 function maskAppSecrets(app) {
   return {
@@ -655,19 +823,14 @@ async function promptPaginationAction() {
     message: "More apps available",
     options: [
       { label: "Load next page", value: "next" },
-      { label: "Load all remaining pages", value: "all" },
+      { label: "Load next 5 pages", value: "next5" },
       { label: "Stop here", value: "stop" }
     ],
     initialValue: "next",
     cancelMessage: "Stopped pagination."
   });
-  if (action === null) {
-    return "stop";
-  }
-  if (action === "next" || action === "all" || action === "stop") {
-    return action;
-  }
-  return "stop";
+  if (action === null) return "stop";
+  return action;
 }
 function matchesSearch(app, query) {
   const q = query.toLowerCase();
@@ -760,7 +923,7 @@ function registerApps(program2) {
       const interactivePagination = isInteractiveAllowed(program2) && !opts.all;
       if (interactivePagination) {
         let page = result;
-        let autoFetchRemaining = false;
+        let batchRemaining = 0;
         let pagesFetched = 0;
         let appsFetched = 0;
         while (true) {
@@ -777,7 +940,7 @@ function registerApps(program2) {
             printFetchSummary(appsFetched, pagesFetched);
             return;
           }
-          if (!autoFetchRemaining) {
+          if (batchRemaining <= 0) {
             printFetchSummary(appsFetched, pagesFetched, { suffix: "so far" });
             const action = await promptPaginationAction();
             if (action === "stop") {
@@ -786,9 +949,11 @@ function registerApps(program2) {
               printFetchSummary(appsFetched, pagesFetched);
               return;
             }
-            if (action === "all") {
-              autoFetchRemaining = true;
+            if (action === "next5") {
+              batchRemaining = 4;
             }
+          } else {
+            batchRemaining -= 1;
           }
           page = await withSpinner(
             "Fetching next page\u2026",
@@ -1003,6 +1168,45 @@ function registerApps(program2) {
       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);
+      const chains = await withSpinner(
+        "Fetching chains\u2026",
+        "Chains fetched",
+        () => admin.listChains()
+      );
+      if (isJSONMode()) {
+        printJSON(chains);
+        return;
+      }
+      if (chains.length === 0) {
+        emptyState("No chain networks were returned.");
+        return;
+      }
+      const formatChainId = (value) => {
+        if (!value) return dim("\u2014");
+        const num = parseInt(value, 10);
+        if (isNaN(num)) return value;
+        return `${num} (0x${num.toString(16)})`;
+      };
+      const rows = chains.map((c) => [
+        c.id,
+        c.name,
+        formatChainId(c.networkChainId),
+        c.isTestnet ? dim("yes") : "no",
+        c.availability === "public" ? green(c.availability) : dim(c.availability),
+        c.currency
+      ]);
+      printTable(["ID", "Name", "Chain ID", "Testnet", "Availability", "Currency"], rows);
+      if (verbose) {
+        console.log("");
+        printJSON(chains);
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
 }
 
 // src/commands/setup.ts
@@ -1063,7 +1267,7 @@ function normalizeTraceMethod(method) {
   return `trace_${normalized}`;
 }
 function registerTrace(program2) {
-  program2.command("trace <method> [params...]").description("Call a trace_* method").action(async (method, params) => {
+  program2.command("trace").argument("<method>", "Trace method name (e.g. trace_transaction)").argument("[params...]", "Method parameters as JSON values").description("Call a trace_* method").action(async (method, params) => {
     try {
       const client = clientFromFlags(program2);
       const rpcMethod = normalizeTraceMethod(method);
@@ -1085,7 +1289,7 @@ function normalizeDebugMethod(method) {
   return `debug_${method.replace(/-/g, "_")}`;
 }
 function registerDebug(program2) {
-  program2.command("debug <method> [params...]").description("Call a debug_* method").action(async (method, params) => {
+  program2.command("debug").argument("<method>", "Debug method name (e.g. debug_traceTransaction)").argument("[params...]", "Method parameters as JSON values").description("Call a debug_* method").action(async (method, params) => {
     try {
       const client = clientFromFlags(program2);
       const rpcMethod = normalizeDebugMethod(method);
@@ -1102,29 +1306,72 @@ function registerDebug(program2) {
 }
 
 // src/commands/transfers.ts
+async function promptTransfersPagination(shown) {
+  const action = await promptSelect({
+    message: `${shown} transfers loaded \u2014 more available`,
+    options: [
+      { label: "Load next page", value: "next" },
+      { label: "Stop here", value: "stop" }
+    ],
+    initialValue: "next",
+    cancelMessage: "Stopped pagination."
+  });
+  if (action === null) return "stop";
+  return action;
+}
+var TABLE_HEADERS = ["Block", "From", "To", "Value", "Asset", "Category"];
+function formatTransferRows(transfers) {
+  return transfers.map((t) => {
+    const block = t.blockNum ? String(parseInt(t.blockNum, 16)) : dim("\u2014");
+    const from = t.from ? `${t.from.slice(0, 8)}\u2026${t.from.slice(-4)}` : dim("\u2014");
+    const to = t.to ? `${t.to.slice(0, 8)}\u2026${t.to.slice(-4)}` : dim("contract creation");
+    const value = t.value !== null && t.value !== void 0 ? String(t.value) : dim("\u2014");
+    const asset = t.asset ?? dim("\u2014");
+    const category = t.category;
+    return [block, from, to, value, asset, category];
+  });
+}
 function registerTransfers(program2) {
-  program2.command("transfers [address]").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").option("--page-key <key>", "Pagination key").action(async (addressArg, opts) => {
+  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(
+    "after",
+    `
+Examples:
+  # Outgoing transfers from an address
+  alchemy transfers 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+  # Incoming transfers to an address
+  alchemy transfers --to-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+  # Outgoing ERC-20 transfers only
+  alchemy transfers --from-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --category erc20
+
+  # Transfers within a block range
+  alchemy transfers 0xd8dA... --from-block 0x100000 --to-block latest`
+  ).action(async (addressArg, opts) => {
     try {
       const client = clientFromFlags(program2);
-      const address = addressArg ?? void 0;
-      if (address) validateAddress(address);
-      if (opts.fromAddress) validateAddress(opts.fromAddress);
-      if (opts.toAddress) validateAddress(opts.toAddress);
-      const filter = {
+      const address = addressArg ? await resolveAddress(addressArg, client) : void 0;
+      if (opts.fromAddress) opts.fromAddress = await resolveAddress(opts.fromAddress, client);
+      if (opts.toAddress) opts.toAddress = await resolveAddress(opts.toAddress, client);
+      const baseFilter = {
         fromBlock: opts.fromBlock ?? "0x0",
         toBlock: opts.toBlock ?? "latest",
-        withMetadata: true
+        withMetadata: true,
+        category: opts.category ? splitCommaList(opts.category) : ["external", "internal", "erc20", "erc721", "erc1155", "specialnft"]
       };
+      if (opts.maxCount) {
+        baseFilter.maxCount = opts.maxCount.startsWith("0x") ? opts.maxCount : `0x${Number.parseInt(opts.maxCount, 10).toString(16)}`;
+      } else if (!isJSONMode()) {
+        baseFilter.maxCount = "0x19";
+      }
+      if (opts.pageKey) baseFilter.pageKey = opts.pageKey;
+      const filter = { ...baseFilter };
       if (address && !opts.fromAddress && !opts.toAddress) {
         filter.fromAddress = address;
-        filter.toAddress = address;
       } else {
         if (opts.fromAddress) filter.fromAddress = opts.fromAddress;
         if (opts.toAddress) filter.toAddress = opts.toAddress;
       }
-      if (opts.category) filter.category = splitCommaList(opts.category);
-      if (opts.maxCount) filter.maxCount = opts.maxCount.startsWith("0x") ? opts.maxCount : `0x${Number.parseInt(opts.maxCount, 10).toString(16)}`;
-      if (opts.pageKey) filter.pageKey = opts.pageKey;
       const result = await withSpinner(
         "Fetching transfers\u2026",
         "Transfers fetched",
@@ -1132,8 +1379,43 @@ function registerTransfers(program2) {
       );
       if (isJSONMode()) {
         printJSON(result);
-      } else {
-        printSyntaxJSON(result);
+        return;
+      }
+      let totalShown = result.transfers.length;
+      if (totalShown === 0) {
+        console.log(dim("No transfers found."));
+        return;
+      }
+      console.log(`${totalShown} transfer${totalShown === 1 ? "" : "s"}
+`);
+      printTable(TABLE_HEADERS, formatTransferRows(result.transfers));
+      const interactive = isInteractiveAllowed(program2);
+      let pageKey = result.pageKey;
+      while (pageKey && interactive) {
+        const action = await promptTransfersPagination(totalShown);
+        if (action === "stop") {
+          console.log(`
+  ${dim(`Next page key: ${pageKey}`)}`);
+          break;
+        }
+        filter.pageKey = pageKey;
+        const nextResult = await withSpinner(
+          "Fetching next page\u2026",
+          "Page fetched",
+          () => client.call("alchemy_getAssetTransfers", [filter])
+        );
+        if (nextResult.transfers.length > 0) {
+          totalShown += nextResult.transfers.length;
+          console.log(`
+${totalShown} transfers total
+`);
+          printTable(TABLE_HEADERS, formatTransferRows(nextResult.transfers));
+        }
+        pageKey = nextResult.pageKey;
+      }
+      if (pageKey && !interactive) {
+        console.log(`
+  ${dim(`More results available. Use --page-key ${pageKey} to see the next page.`)}`);
       }
     } catch (err) {
       exitWithError(err);
@@ -1587,7 +1869,7 @@ function registerSolana(program2) {
   const cmd = program2.command("solana").description("Solana RPC and DAS wrappers");
   cmd.command("rpc <method> [params...]").description("Call a Solana JSON-RPC method").action(async (method, params) => {
     try {
-      const client = clientFromFlags(program2);
+      const client = clientFromFlags(program2, { defaultNetwork: "solana-mainnet" });
       const result = await withSpinner(
         `Calling ${method}\u2026`,
         `Called ${method}`,
@@ -1598,14 +1880,15 @@ function registerSolana(program2) {
       exitWithError(err);
     }
   });
-  const das = cmd.command("das").description("Solana DAS (Digital Asset Standard) wrappers");
-  das.command("<method> [params...]").description("Call DAS method (e.g. getAssetsByOwner)").action(async (method, params) => {
+  cmd.command("das <method> [params...]").description("Call a Solana DAS method (e.g. getAssetsByOwner)").action(async (method, params) => {
     try {
-      const client = clientFromFlags(program2);
+      const client = clientFromFlags(program2, { defaultNetwork: "solana-mainnet" });
+      const parsed = parseCLIParams(params);
+      const rpcParams = parsed.length === 1 && typeof parsed[0] === "object" && parsed[0] !== null && !Array.isArray(parsed[0]) ? parsed[0] : parsed;
       const result = await withSpinner(
         `Calling ${method}\u2026`,
         `Called ${method}`,
-        () => client.call(method, parseCLIParams(params))
+        () => client.call(method, rpcParams)
       );
       printSyntaxJSON(result);
     } catch (err) {
@@ -1614,6 +1897,311 @@ function registerSolana(program2) {
   });
 }
 
+// src/commands/gas.ts
+function registerGas(program2) {
+  program2.command("gas").description("Get current gas prices (base fee + priority fee)").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy gas
+  alchemy gas -n polygon-mainnet
+  alchemy gas --json`
+  ).action(async () => {
+    try {
+      const client = clientFromFlags(program2);
+      const [gasPrice, maxPriorityFee] = await withSpinner(
+        "Fetching gas prices\u2026",
+        "Gas prices fetched",
+        async () => {
+          const [gp, mpf] = await Promise.all([
+            client.call("eth_gasPrice", []),
+            client.call("eth_maxPriorityFeePerGas", []).catch(() => null)
+          ]);
+          return [gp, mpf];
+        }
+      );
+      const network = resolveNetwork(program2);
+      const gasPriceWei = BigInt(gasPrice);
+      const gasPriceGwei = Number(gasPriceWei) / 1e9;
+      let priorityFeeGwei = null;
+      let priorityFeeWei = null;
+      if (maxPriorityFee) {
+        priorityFeeWei = BigInt(maxPriorityFee);
+        priorityFeeGwei = Number(priorityFeeWei) / 1e9;
+      }
+      if (isJSONMode()) {
+        const json = {
+          gasPrice,
+          gasPriceGwei: formatGwei(gasPriceGwei),
+          network
+        };
+        if (maxPriorityFee) {
+          json.maxPriorityFeePerGas = maxPriorityFee;
+          json.maxPriorityFeePerGasGwei = formatGwei(priorityFeeGwei);
+        }
+        printJSON(json);
+      } else {
+        const pairs = [];
+        const gasPriceFormatted = formatGweiWithRaw(gasPrice);
+        pairs.push(["Gas Price", gasPriceFormatted ?? `${formatGwei(gasPriceGwei)} gwei`]);
+        if (maxPriorityFee && priorityFeeGwei !== null) {
+          const priorityFormatted = formatGweiWithRaw(maxPriorityFee);
+          pairs.push(["Priority Fee", priorityFormatted ?? `${formatGwei(priorityFeeGwei)} gwei`]);
+        }
+        pairs.push(["Network", network]);
+        printKeyValueBox(pairs);
+        if (verbose) {
+          console.log("");
+          const verboseData = {
+            rpcMethod: "eth_gasPrice",
+            rpcResult: gasPrice
+          };
+          if (maxPriorityFee) {
+            verboseData.rpcMethod2 = "eth_maxPriorityFeePerGas";
+            verboseData.rpcResult2 = maxPriorityFee;
+          }
+          printJSON(verboseData);
+        }
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/logs.ts
+var PAGE_SIZE = 25;
+var LARGE_PAGE_SIZE = 100;
+function normalizeBlockParam(value) {
+  if (value === "latest" || value === "earliest" || value === "pending") {
+    return value;
+  }
+  if (value.startsWith("0x")) return value;
+  const num = parseInt(value, 10);
+  if (isNaN(num) || num < 0) {
+    throw errInvalidArgs("Block must be a number, hex, or tag (latest, earliest, pending).");
+  }
+  return `0x${num.toString(16)}`;
+}
+function formatLogRows(logs) {
+  return logs.map((log) => {
+    const block = formatHexQuantity(log.blockNumber) ?? log.blockNumber;
+    const idx = formatHexQuantity(log.logIndex) ?? log.logIndex;
+    const topic0 = log.topics[0] ? `${log.topics[0].slice(0, 10)}\u2026` : dim("none");
+    const addr = log.address;
+    const txHash = `${log.transactionHash.slice(0, 10)}\u2026`;
+    return [block, idx, addr, topic0, txHash];
+  });
+}
+var TABLE_HEADERS2 = ["Block", "Index", "Address", "Topic0", "Tx Hash"];
+async function promptPaginationAction2(shown, total) {
+  const remaining = total - shown;
+  const options = [
+    { label: `Show next ${Math.min(PAGE_SIZE, remaining)}`, value: "next" }
+  ];
+  if (remaining > PAGE_SIZE) {
+    options.push({ label: `Show next ${Math.min(LARGE_PAGE_SIZE, remaining)}`, value: "next-large" });
+  }
+  options.push({ label: "Stop here", value: "stop" });
+  const action = await promptSelect({
+    message: `Showing ${shown} of ${total} logs (${remaining} remaining)`,
+    options,
+    initialValue: "next",
+    cancelMessage: "Stopped pagination."
+  });
+  if (action === null) return "stop";
+  return action;
+}
+function registerLogs(program2) {
+  program2.command("logs").description("Query event logs (eth_getLogs)").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy logs --from-block 18000000 --to-block 18000010
+  alchemy logs --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 --from-block 18000000 --to-block 18000010
+  alchemy logs --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 --topic 0xddf252ad...
+  alchemy logs --from-block latest --json`
+  ).option("--address <address>", "Contract address to filter logs").option("--topic <topic...>", "Event topic(s) to filter (topic0, topic1, ...)").option("--from-block <block>", "Start block (number, hex, or tag)", "latest").option("--to-block <block>", "End block (number, hex, or tag)", "latest").action(async (opts) => {
+    try {
+      const filter = {
+        fromBlock: normalizeBlockParam(opts.fromBlock),
+        toBlock: normalizeBlockParam(opts.toBlock)
+      };
+      if (opts.address) {
+        filter.address = opts.address;
+      }
+      if (opts.topic && opts.topic.length > 0) {
+        filter.topics = opts.topic;
+      }
+      const client = clientFromFlags(program2);
+      const logs = await withSpinner(
+        "Fetching logs\u2026",
+        "Logs fetched",
+        () => client.call("eth_getLogs", [filter])
+      );
+      const network = resolveNetwork(program2);
+      if (isJSONMode()) {
+        printJSON({ logs, count: logs.length, network });
+        return;
+      }
+      if (logs.length === 0) {
+        console.log(dim("No logs found for the given filter."));
+        return;
+      }
+      const total = logs.length;
+      const interactive = isInteractiveAllowed(program2);
+      if (!interactive) {
+        console.log(`Found ${total} log${total === 1 ? "" : "s"} on ${network}
+`);
+        printTable(TABLE_HEADERS2, formatLogRows(logs));
+      } else {
+        let offset = 0;
+        const firstPage = logs.slice(0, PAGE_SIZE);
+        console.log(`Found ${total} log${total === 1 ? "" : "s"} on ${network}
+`);
+        printTable(TABLE_HEADERS2, formatLogRows(firstPage));
+        offset = firstPage.length;
+        while (offset < total) {
+          const action = await promptPaginationAction2(offset, total);
+          if (action === "stop") break;
+          const size = action === "next-large" ? LARGE_PAGE_SIZE : PAGE_SIZE;
+          const page = logs.slice(offset, offset + size);
+          console.log("");
+          printTable(TABLE_HEADERS2, formatLogRows(page));
+          offset += page.length;
+        }
+      }
+      if (total >= 1e4) {
+        console.log("");
+        console.log(dim("\u26A0 RPC result limit reached (10,000). Narrow your block range for complete results."));
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/completions.ts
+function getDescription(cmd) {
+  try {
+    return typeof cmd.description === "function" ? cmd.description() : String(cmd.description || "");
+  } catch {
+    return "";
+  }
+}
+function collectCommands(cmd, prefix = []) {
+  const results = [];
+  for (const sub of cmd.commands) {
+    const path = [...prefix, sub.name()];
+    results.push({ path, description: getDescription(sub) });
+    results.push(...collectCommands(sub, path));
+  }
+  return results;
+}
+function generateBash(program2) {
+  const commands = collectCommands(program2);
+  const topLevel = program2.commands.map((c) => c.name()).join(" ");
+  const cases = commands.filter((c) => c.path.length === 1).map((c) => {
+    const subs = commands.filter((s) => s.path.length === 2 && s.path[0] === c.path[0]).map((s) => s.path[1]);
+    if (subs.length === 0) return "";
+    return `      ${c.path[0]}) COMPREPLY=($(compgen -W "${subs.join(" ")}" -- "$cur")) ;;`;
+  }).filter(Boolean).join("\n");
+  return `# bash completion for alchemy CLI
+# Add to ~/.bashrc: eval "$(alchemy completions bash)"
+_alchemy_completions() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=($(compgen -W "${topLevel}" -- "$cur"))
+    return
+  fi
+
+  case "$prev" in
+${cases}
+      -n|--network) COMPREPLY=() ;;
+      *) COMPREPLY=() ;;
+  esac
+}
+complete -F _alchemy_completions alchemy
+`;
+}
+function generateZsh(program2) {
+  const commands = collectCommands(program2);
+  const topLevel = program2.commands.map((c) => `'${c.name()}:${getDescription(c).replace(/'/g, "'\\''")}'`).join("\n      ");
+  const subcommandCases = commands.filter((c) => c.path.length === 1).map((c) => {
+    const subs = commands.filter((s) => s.path.length === 2 && s.path[0] === c.path[0]).map((s) => `'${s.path[1]}:${s.description.replace(/'/g, "'\\''")}'`);
+    if (subs.length === 0) return "";
+    return `    ${c.path[0]})
+      _values 'subcommand' \\
+        ${subs.join(" \\\n        ")}
+      ;;`;
+  }).filter(Boolean).join("\n");
+  return `#compdef alchemy
+# zsh completion for alchemy CLI
+# Add to ~/.zshrc: eval "$(alchemy completions zsh)"
+_alchemy() {
+  local -a commands
+  if (( CURRENT == 2 )); then
+    commands=(
+      ${topLevel}
+    )
+    _describe 'command' commands
+    return
+  fi
+
+  case "$words[2]" in
+${subcommandCases}
+  esac
+}
+_alchemy "$@"
+compdef _alchemy alchemy
+`;
+}
+function generateFish(program2) {
+  const commands = collectCommands(program2);
+  const lines = commands.map((c) => {
+    const desc = c.description.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    if (c.path.length === 1) {
+      return `complete -c alchemy -n '__fish_use_subcommand' -a '${c.path[0]}' -d '${desc}'`;
+    }
+    if (c.path.length === 2) {
+      return `complete -c alchemy -n '__fish_seen_subcommand_from ${c.path[0]}' -a '${c.path[1]}' -d '${desc}'`;
+    }
+    return "";
+  }).filter(Boolean);
+  return `# fish completion for alchemy CLI
+# Add to ~/.config/fish/completions/alchemy.fish
+${lines.join("\n")}
+`;
+}
+function registerCompletions(program2) {
+  program2.command("completions").argument("<shell>", "Shell type: bash, zsh, or fish").description("Generate shell completion scripts").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy completions bash >> ~/.bashrc
+  eval "$(alchemy completions zsh)"
+  alchemy completions fish > ~/.config/fish/completions/alchemy.fish`
+  ).action((shell) => {
+    switch (shell.toLowerCase()) {
+      case "bash":
+        process.stdout.write(generateBash(program2));
+        break;
+      case "zsh":
+        process.stdout.write(generateZsh(program2));
+        break;
+      case "fish":
+        process.stdout.write(generateFish(program2));
+        break;
+      default:
+        console.error(`Unknown shell: ${shell}. Supported: bash, zsh, fish`);
+        process.exit(2);
+    }
+  });
+}
+
 // src/commands/agent-prompt.ts
 var RETRYABLE_CODES = /* @__PURE__ */ new Set([
   ErrorCode.RATE_LIMITED,
@@ -1715,7 +2303,7 @@ function buildAgentPrompt(program2) {
         envVar: "ALCHEMY_ACCESS_KEY",
         flag: "--access-key <key>",
         configKey: "access-key",
-        commandFamilies: ["apps", "chains", "network list --configured"]
+        commandFamilies: ["apps", "network list --configured"]
       },
       {
         method: "Webhook API key",
@@ -1847,7 +2435,7 @@ var ROOT_OPTION_GROUPS = [
 var ROOT_COMMAND_PILLARS = [
   {
     label: "Node",
-    commands: ["balance", "tx", "block", "rpc", "trace", "debug"]
+    commands: ["balance", "tx", "block", "rpc", "trace", "debug", "gas", "logs"]
   },
   {
     label: "Data",
@@ -1859,11 +2447,11 @@ var ROOT_COMMAND_PILLARS = [
   },
   {
     label: "Chains",
-    commands: ["network", "chains", "solana"]
+    commands: ["network", "solana"]
   },
   {
     label: "Admin",
-    commands: ["apps", "config", "setup", "agent-prompt", "update-check", "version", "help"]
+    commands: ["apps", "config", "setup", "completions", "agent-prompt", "update-check", "version", "help"]
   }
 ];
 function formatCommandSignature(sub) {
@@ -1912,10 +2500,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.2.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.3.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").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).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 (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) => {
   if (err.code === "commander.help" || err.code === "commander.helpDisplayed" || err.code === "commander.version") {
     process.exit(0);
   }
@@ -2028,6 +2616,14 @@ ${styledLine}`;
 }).addHelpText("beforeAll", () => isHelpInvocation ? brandedHelp() : "").addHelpText("after", () => {
   if (isJSONMode()) return "";
   return [
+    "",
+    `${hBrand("\u25C6")} ${hBold("Quick Start")}`,
+    `  ${hDim("\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")}`,
+    `  ${hBrand("alchemy")}                              ${hDim("Interactive mode with guided setup")}`,
+    `  ${hBrand("alchemy balance")} ${hDim("<address>")}             ${hDim("Get native token balance")}`,
+    `  ${hBrand("alchemy block latest")}                  ${hDim("Latest block summary")}`,
+    `  ${hBrand("alchemy rpc eth_chainId")}               ${hDim("Raw JSON-RPC call")}`,
+    `  ${hBrand("alchemy config list")}                   ${hDim("View current configuration")}`,
     "",
     `${hBrand("\u25C6")} ${hBold("Exit Codes")}`,
     `  ${hDim("\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")}`,
@@ -2067,7 +2663,15 @@ ${styledLine}`;
     }
   }
   resetUpdateNoticeState();
-}).action(async () => {
+}).action(async (_opts, cmd) => {
+  const excessArgs = cmd.args;
+  if (excessArgs.length > 0) {
+    exitWithError(
+      errInvalidArgs(
+        `Unknown command '${excessArgs[0]}'. Run 'alchemy help' for available commands.`
+      )
+    );
+  }
   const cfg = load();
   if (!isSetupComplete(cfg) && !isInteractiveAllowed(program)) {
     throw errSetupRequired(getSetupStatus(cfg));
@@ -2075,7 +2679,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-YA32OJOT.js");
+      const { runOnboarding } = await import("./onboarding-MUJF5QIE.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -2087,7 +2691,7 @@ ${styledLine}`;
       latestForInteractiveStartup = getAvailableUpdateOnce();
       updateShownDuringInteractiveStartup = Boolean(latestForInteractiveStartup);
     }
-    const { startREPL } = await import("./interactive-L7N4HI7K.js");
+    const { startREPL } = await import("./interactive-BFAXB5SN.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {
@@ -2101,9 +2705,12 @@ ${styledLine}`;
 registerRPC(program);
 registerBalance(program);
 registerTx(program);
+registerReceipt(program);
 registerBlock(program);
 registerTrace(program);
 registerDebug(program);
+registerGas(program);
+registerLogs(program);
 registerTokens(program);
 registerNFTs(program);
 registerTransfers(program);
@@ -2115,12 +2722,12 @@ registerBundler(program);
 registerGasManager(program);
 registerWebhooks(program);
 registerNetwork(program);
-registerChains(program);
 registerApps(program);
 registerSetup(program);
 registerConfig(program);
 registerSolana(program);
 registerAgentPrompt(program);
+registerCompletions(program);
 registerUpdateCheck(program);
 registerVersion(program);
 program.command("help [command...]").description("display help for command").action((commandPath) => {