@alchemy/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1897 @@
+#!/usr/bin/env node
+if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
+import {
+  adminClientFromFlags,
+  clientFromFlags,
+  fetchWithTimeout,
+  readStdinArg,
+  registerConfig,
+  registerWallet,
+  resolveAPIKey,
+  resolveAppId,
+  resolveConfiguredNetworkSlugs,
+  resolveNetwork,
+  splitCommaList,
+  validateAddress,
+  validateTxHash
+} from "./chunk-PH4BPYSY.js";
+import {
+  getRPCNetworks,
+  getSetupStatus,
+  isSetupComplete,
+  shouldRunOnboarding
+} from "./chunk-F7KTEZFZ.js";
+import {
+  bold,
+  brand,
+  brandedHelp,
+  debug,
+  dim,
+  emptyState,
+  errAuthRequired,
+  errInvalidAPIKey,
+  errInvalidArgs,
+  errNetwork,
+  errNotFound,
+  errRateLimited,
+  errSetupRequired,
+  esc,
+  etherscanTxURL,
+  exitWithError,
+  failBadge,
+  formatCommanderError,
+  green,
+  identity,
+  isInteractiveAllowed,
+  isJSONMode,
+  load,
+  maskIf,
+  noColor,
+  printHuman,
+  printJSON,
+  printKeyValueBox,
+  printSyntaxJSON,
+  printTable,
+  promptSelect,
+  quiet,
+  setFlags,
+  successBadge,
+  timeAgo,
+  verbose,
+  weiToEth,
+  withSpinner
+} from "./chunk-QKXQW4OF.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(
+    "after",
+    `
+Examples:
+  alchemy rpc eth_blockNumber
+  alchemy rpc eth_getBalance "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" "latest"
+  alchemy rpc eth_getBlockByNumber "0x1" true`
+  ).action(async (method, params) => {
+    try {
+      const client = clientFromFlags(program2);
+      const parsed = params.map((p) => {
+        try {
+          return JSON.parse(p);
+        } catch {
+          return p;
+        }
+      });
+      debug(`rpc ${method} %o`, parsed);
+      const result = await withSpinner(
+        `Calling ${method}\u2026`,
+        `Called ${method}`,
+        () => client.call(method, parsed)
+      );
+      printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/balance.ts
+function registerBalance(program2) {
+  program2.command("balance [address]").alias("bal").description("Get the ETH balance of an address").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+  alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n polygon-mainnet
+  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy balance`
+  ).action(async (addressArg) => {
+    try {
+      const address = addressArg ?? await readStdinArg("address");
+      validateAddress(address);
+      const client = clientFromFlags(program2);
+      const result = await withSpinner(
+        "Fetching balance\u2026",
+        "Balance fetched",
+        () => client.call("eth_getBalance", [address, "latest"])
+      );
+      const wei = BigInt(result);
+      const network = resolveNetwork(program2);
+      if (isJSONMode()) {
+        printJSON({
+          address,
+          wei: wei.toString(),
+          eth: weiToEth(wei),
+          network
+        });
+      } else {
+        printKeyValueBox([
+          ["Address", address],
+          ["Balance", green(weiToEth(wei) + " ETH")],
+          ["Network", network]
+        ]);
+        if (verbose) {
+          console.log("");
+          printJSON({
+            rpcMethod: "eth_getBalance",
+            rpcParams: [address, "latest"],
+            rpcResult: result
+          });
+        }
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/tx.ts
+function registerTx(program2) {
+  program2.command("tx [hash]").description("Get transaction details by hash").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy tx 0xabc123...
+  echo 0xabc123... | alchemy tx`
+  ).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 t = await client.call("eth_getTransactionByHash", [
+          hash
+        ]);
+        if (!t) throw errNotFound(`transaction ${hash}`);
+        const r = await client.call("eth_getTransactionReceipt", [
+          hash
+        ]);
+        return [t, r];
+      });
+      if (isJSONMode()) {
+        printJSON({ transaction: tx, receipt });
+        return;
+      }
+      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")]);
+      }
+      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)]);
+      }
+      const network = resolveNetwork(program2);
+      const explorerURL = etherscanTxURL(hash, network);
+      if (explorerURL) {
+        pairs.push(["Explorer", explorerURL]);
+      }
+      printKeyValueBox(pairs);
+      if (verbose) {
+        console.log("");
+        printJSON({ transaction: tx, receipt });
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// 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/block.ts
+function registerBlock(program2) {
+  program2.command("block <number>").description("Get block details by number").addHelpText(
+    "after",
+    `
+Examples:
+  alchemy block latest
+  alchemy block 17000000
+  alchemy block 0x1`
+  ).action(async (blockId) => {
+    try {
+      let blockParam;
+      if (["latest", "earliest", "pending"].includes(blockId)) {
+        blockParam = blockId;
+      } else if (blockId.startsWith("0x")) {
+        blockParam = blockId;
+      } else {
+        const num = parseInt(blockId, 10);
+        if (isNaN(num)) {
+          throw errInvalidArgs(
+            "block must be a number, hex, or 'latest'"
+          );
+        }
+        blockParam = `0x${num.toString(16)}`;
+      }
+      const client = clientFromFlags(program2);
+      const block = await withSpinner(
+        "Fetching block\u2026",
+        "Block fetched",
+        () => client.call("eth_getBlockByNumber", [blockParam, false])
+      );
+      if (!block) throw errNotFound(`block ${blockId}`);
+      if (isJSONMode()) {
+        printJSON(block);
+        return;
+      }
+      const pairs = [];
+      if (block.number) {
+        const formatted = formatHexQuantity(block.number);
+        pairs.push(["Block", bold(formatted ?? String(block.number))]);
+      }
+      if (block.hash) pairs.push(["Hash", String(block.hash)]);
+      if (block.timestamp) {
+        const ts = formatBlockTimestamp(block.timestamp);
+        if (ts) pairs.push(["Timestamp", ts]);
+      }
+      if (Array.isArray(block.transactions)) {
+        const txCount = block.transactions.length.toLocaleString("en-US");
+        pairs.push(["Transactions", txCount]);
+      }
+      if (block.miner) pairs.push(["Miner", String(block.miner)]);
+      const gasSummary = formatGasSummary(block.gasUsed, block.gasLimit, { colored: true });
+      if (gasSummary) {
+        pairs.push(["Gas", gasSummary]);
+      } else {
+        if (block.gasUsed) {
+          const formatted = formatHexQuantity(block.gasUsed);
+          pairs.push(["Gas Used", formatted ?? String(block.gasUsed)]);
+        }
+        if (block.gasLimit) {
+          const formatted = formatHexQuantity(block.gasLimit);
+          pairs.push(["Gas Limit", formatted ?? String(block.gasLimit)]);
+        }
+      }
+      printKeyValueBox(pairs);
+      if (verbose) {
+        console.log("");
+        printSyntaxJSON(block);
+      } else {
+        console.log("");
+        console.log(`  ${dim("Tip: use --verbose to include the raw block payload.")}`);
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/nfts.ts
+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(
+    "after",
+    `
+Examples:
+  alchemy nfts 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+  alchemy nfts metadata --contract 0x... --token-id 1
+  alchemy nfts contract 0x...
+  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy nfts`
+  ).action(async (addressArg, opts) => {
+    try {
+      const address = addressArg ?? await readStdinArg("address");
+      validateAddress(address);
+      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",
+        () => client.callEnhanced("getNFTsForOwner", params)
+      );
+      if (isJSONMode()) {
+        printJSON(result);
+        return;
+      }
+      if (result.ownedNfts.length === 0) {
+        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);
+      if (verbose) {
+        console.log("");
+        printJSON(result);
+      }
+      if (result.pageKey) {
+        console.log(`
+  ${dim(`More results available. Use --page-key ${result.pageKey} to see the next page.`)}`);
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("metadata").description("Get NFT metadata by contract/token").requiredOption("--contract <address>", "NFT contract address").requiredOption("--token-id <id>", "Token id").action(async (opts) => {
+    try {
+      validateAddress(opts.contract);
+      const client = clientFromFlags(program2);
+      const result = await withSpinner(
+        "Fetching NFT metadata\u2026",
+        "NFT metadata fetched",
+        () => client.callEnhanced("getNFTMetadata", {
+          contractAddress: opts.contract,
+          tokenId: opts.tokenId
+        })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("contract <address>").description("Get NFT contract metadata").action(async (address) => {
+    try {
+      validateAddress(address);
+      const client = clientFromFlags(program2);
+      const result = await withSpinner(
+        "Fetching contract metadata\u2026",
+        "Contract metadata fetched",
+        () => client.callEnhanced("getContractMetadata", {
+          contractAddress: address
+        })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/tokens.ts
+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(
+    "after",
+    `
+Examples:
+  alchemy tokens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+  alchemy tokens metadata 0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eB48
+  alchemy tokens allowance --owner 0x... --spender 0x... --contract 0x...
+  echo 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | alchemy tokens`
+  ).action(async (addressArg, opts) => {
+    try {
+      const address = addressArg ?? await readStdinArg("address");
+      validateAddress(address);
+      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",
+        () => client.call("alchemy_getTokenBalances", params)
+      );
+      if (isJSONMode()) {
+        printJSON(result);
+        return;
+      }
+      const nonZero = result.tokenBalances.filter(
+        (tb) => tb.tokenBalance !== "0x0" && tb.tokenBalance !== "0x0000000000000000000000000000000000000000000000000000000000000000"
+      );
+      if (nonZero.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];
+      });
+      printKeyValueBox([
+        ["Address", address],
+        ["Network", client.network],
+        ["Non-zero tokens", String(nonZero.length)]
+      ]);
+      printTable(["Contract", "Balance (base units)", "Raw (hex)"], rows);
+      console.log(`
+  ${dim(`Showing ${nonZero.length} of ${result.tokenBalances.length} contracts (non-zero only).`)}`);
+      if (verbose) {
+        console.log("");
+        printJSON(result);
+      }
+      if (result.pageKey) {
+        console.log(`
+  ${dim(`More results available. Use --page-key ${result.pageKey} to see the next page.`)}`);
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("metadata <contract>").description("Get ERC-20 token metadata").action(async (contract) => {
+    try {
+      validateAddress(contract);
+      const client = clientFromFlags(program2);
+      const result = await withSpinner(
+        "Fetching token metadata\u2026",
+        "Token metadata fetched",
+        () => client.call("alchemy_getTokenMetadata", [contract])
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("allowance").description("Get ERC-20 token allowance").requiredOption("--owner <address>", "Owner address").requiredOption("--spender <address>", "Spender address").requiredOption("--contract <address>", "Token contract address").action(async (opts) => {
+    try {
+      validateAddress(opts.owner);
+      validateAddress(opts.spender);
+      validateAddress(opts.contract);
+      const client = clientFromFlags(program2);
+      const result = await withSpinner(
+        "Fetching token allowance\u2026",
+        "Token allowance fetched",
+        () => client.call("alchemy_getTokenAllowance", [
+          opts.owner,
+          opts.spender,
+          opts.contract
+        ])
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// 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(
+    "--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) => {
+    try {
+      const supported = 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 (isJSONMode()) {
+        if (configured) {
+          printJSON({
+            mode: "configured",
+            appId,
+            configuredNetworkIds: configured,
+            networks: display
+          });
+          return;
+        }
+        printJSON(display);
+        return;
+      }
+      const rows = display.map((network) => {
+        const isCurrent = network.id === current;
+        const idCell = isCurrent ? green(network.id) : network.id;
+        const nameCell = isCurrent ? green(network.name) : network.name;
+        const testnetCell = network.isTestnet ? dim("yes") : "no";
+        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 enums instead? Run: alchemy chains list")}`
+      );
+      if (verbose) {
+        console.log("");
+        printJSON({
+          mode: configured ? "configured" : "all",
+          appId: appId ?? null,
+          configuredNetworkIds: configured ?? null,
+          networks: display,
+          currentNetwork: current
+        });
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/version.ts
+function registerVersion(program2) {
+  program2.command("version").description("Print the CLI version").action(() => {
+    const version = program2.version() || "dev";
+    printHuman(`  ${brand("\u25C6")} ${bold("alchemy-cli")} ${version}
+`, { version });
+  });
+}
+
+// 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 {
+    ...app,
+    ...app.apiKey !== void 0 && { apiKey: maskIf(app.apiKey) },
+    ...app.webhookApiKey !== void 0 && { webhookApiKey: maskIf(app.webhookApiKey) }
+  };
+}
+function printFetchSummary(appsCount, pagesCount, opts) {
+  const suffix = opts?.suffix ? ` ${opts.suffix}` : "";
+  console.log(`
+  ${dim(`Fetched ${appsCount} apps across ${pagesCount} pages${suffix}`)}`);
+}
+async function promptPaginationAction() {
+  const action = await promptSelect({
+    message: "More apps available",
+    options: [
+      { label: "Load next page", value: "next" },
+      { label: "Load all remaining pages", value: "all" },
+      { 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";
+}
+function matchesSearch(app, query) {
+  const q = query.toLowerCase();
+  return app.name.toLowerCase().includes(q) || app.id.toLowerCase().includes(q);
+}
+function appToTableRow(app) {
+  return [app.id, app.name, String(app.chainNetworks.length), app.createdAt];
+}
+function handleDryRun(opts, action, payload, humanMsg) {
+  if (!opts.dryRun) return false;
+  if (isJSONMode()) {
+    printJSON({ dryRun: true, action, payload });
+  } else {
+    console.log(`  ${dim("Dry run:")} ${humanMsg}`);
+  }
+  return true;
+}
+function registerApps(program2) {
+  const cmd = program2.command("apps").description("Manage Alchemy apps");
+  cmd.command("list").description("List all apps").option("--cursor <cursor>", "Pagination cursor").option("--limit <n>", "Max results per page", parseInt).option("--all", "Fetch all pages").option("--search <query>", "Search apps by name or id (client-side)").option("--id <appId>", "Filter by exact app id (client-side)").action(async (opts) => {
+    try {
+      const admin = adminClientFromFlags(program2);
+      const fetchAll = Boolean(opts.all);
+      const hasSearch = typeof opts.search === "string";
+      const hasId = typeof opts.id === "string";
+      const searchQuery = hasSearch ? opts.search.trim() : "";
+      const idQuery = hasId ? opts.id.trim() : "";
+      if (opts.all && opts.cursor) {
+        throw errInvalidArgs("Cannot combine --all with --cursor");
+      }
+      if (hasSearch && hasId) {
+        throw errInvalidArgs("Cannot combine --search with --id");
+      }
+      if (opts.cursor && (hasSearch || hasId)) {
+        throw errInvalidArgs("Cannot combine --cursor with --search or --id");
+      }
+      if (hasSearch && !searchQuery) {
+        throw errInvalidArgs("--search cannot be empty");
+      }
+      if (hasId && !idQuery) {
+        throw errInvalidArgs("--id cannot be empty");
+      }
+      const isFilteredList = hasSearch || hasId;
+      if (fetchAll || isFilteredList) {
+        const result2 = await withSpinner(
+          "Fetching apps\u2026",
+          "Apps fetched",
+          () => admin.listAllApps({ limit: opts.limit })
+        );
+        const filteredApps = hasId ? result2.apps.filter((a) => a.id === idQuery) : hasSearch ? result2.apps.filter((a) => matchesSearch(a, searchQuery)) : result2.apps;
+        if (isJSONMode()) {
+          printJSON({
+            apps: filteredApps.map(maskAppSecrets),
+            pageInfo: {
+              mode: fetchAll ? "all" : "search",
+              pages: result2.pages,
+              scannedApps: result2.apps.length,
+              ...hasSearch && { search: searchQuery },
+              ...hasId && { id: idQuery }
+            }
+          });
+          return;
+        }
+        if (filteredApps.length === 0) {
+          emptyState(
+            hasId ? `No apps found with id "${idQuery}".` : hasSearch ? `No apps found matching "${searchQuery}".` : "No apps found."
+          );
+          printFetchSummary(result2.apps.length, result2.pages);
+          return;
+        }
+        const rows2 = filteredApps.map(appToTableRow);
+        printTable(["ID", "Name", "Networks", "Created"], rows2);
+        if (isFilteredList) {
+          const filterLabel = hasId ? `id "${idQuery}"` : `"${searchQuery}"`;
+          console.log(`
+  ${dim(`Matched ${filteredApps.length} apps for ${filterLabel}`)}`);
+        }
+        printFetchSummary(result2.apps.length, result2.pages);
+        return;
+      }
+      const result = await withSpinner(
+        "Fetching apps\u2026",
+        "Apps fetched",
+        () => admin.listApps({ cursor: opts.cursor, limit: opts.limit })
+      );
+      if (isJSONMode()) {
+        printJSON({ ...result, apps: result.apps.map(maskAppSecrets) });
+        return;
+      }
+      const interactivePagination = isInteractiveAllowed(program2) && !opts.all;
+      if (interactivePagination) {
+        let page = result;
+        let autoFetchRemaining = false;
+        let pagesFetched = 0;
+        let appsFetched = 0;
+        while (true) {
+          if (page.apps.length > 0) {
+            pagesFetched += 1;
+            appsFetched += page.apps.length;
+            const rows2 = page.apps.map(appToTableRow);
+            printTable(["ID", "Name", "Networks", "Created"], rows2);
+          } else {
+            emptyState("No apps found.");
+            return;
+          }
+          if (!page.cursor) {
+            printFetchSummary(appsFetched, pagesFetched);
+            return;
+          }
+          if (!autoFetchRemaining) {
+            printFetchSummary(appsFetched, pagesFetched, { suffix: "so far" });
+            const action = await promptPaginationAction();
+            if (action === "stop") {
+              console.log(`
+  ${dim(`Next cursor: ${page.cursor}`)}`);
+              printFetchSummary(appsFetched, pagesFetched);
+              return;
+            }
+            if (action === "all") {
+              autoFetchRemaining = true;
+            }
+          }
+          page = await withSpinner(
+            "Fetching next page\u2026",
+            "Page fetched",
+            () => admin.listApps({ cursor: page.cursor, limit: opts.limit })
+          );
+        }
+      }
+      if (result.apps.length === 0) {
+        emptyState("No apps found.");
+        return;
+      }
+      const rows = result.apps.map(appToTableRow);
+      printTable(["ID", "Name", "Networks", "Created"], rows);
+      printFetchSummary(result.apps.length, 1);
+      if (result.cursor) {
+        console.log(`
+  ${dim(`Next cursor: ${result.cursor}`)}`);
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("get <id>").description("Get app details").action(async (id) => {
+    try {
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Fetching app\u2026",
+        "App fetched",
+        () => admin.getApp(id)
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      const networks = app.chainNetworks.map((n) => n.name).join(", ");
+      printKeyValueBox([
+        ["ID", app.id],
+        ["Name", app.name],
+        ...app.description ? [["Description", app.description]] : [],
+        ["API Key", maskIf(app.apiKey)],
+        ["Networks", networks || dim("none")],
+        ["Created", app.createdAt]
+      ]);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("create").description("Create a new app").requiredOption("--name <name>", "App name").requiredOption("--networks <networks>", "Comma-separated network IDs").option("--description <desc>", "App description").option("--products <products>", "Comma-separated product IDs").option("--dry-run", "Preview without executing").action(async (opts) => {
+    try {
+      const networks = splitCommaList(opts.networks);
+      const products = opts.products ? splitCommaList(opts.products) : void 0;
+      const payload = {
+        name: opts.name,
+        networks,
+        ...opts.description && { description: opts.description },
+        ...products && { products }
+      };
+      if (handleDryRun(opts, "create", payload, `Would create app "${opts.name}" on networks: ${networks.join(", ")}`)) return;
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Creating app\u2026",
+        "App created",
+        () => admin.createApp({
+          name: opts.name,
+          networks,
+          description: opts.description,
+          products
+        })
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      printKeyValueBox([
+        ["ID", app.id],
+        ["Name", app.name],
+        ["API Key", maskIf(app.apiKey)]
+      ]);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("delete <id>").description("Delete an app").option("--dry-run", "Preview without executing").action(async (id, opts) => {
+    try {
+      if (handleDryRun(opts, "delete", { id }, `Would delete app ${id}`)) return;
+      const admin = adminClientFromFlags(program2);
+      await withSpinner(
+        "Deleting app\u2026",
+        "App deleted",
+        () => admin.deleteApp(id)
+      );
+      if (isJSONMode()) {
+        printJSON({ id, status: "deleted" });
+        return;
+      }
+      console.log(`  ${green("\u2713")} Deleted app ${id}`);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("update <id>").description("Update an app").option("--name <name>", "New app name").option("--description <desc>", "New app description").option("--dry-run", "Preview without executing").action(async (id, opts) => {
+    try {
+      if (!opts.name && !opts.description) {
+        throw errInvalidArgs("Provide at least --name or --description");
+      }
+      const payload = {
+        id,
+        ...opts.name && { name: opts.name },
+        ...opts.description && { description: opts.description }
+      };
+      if (handleDryRun(opts, "update", payload, `Would update app ${id}`)) return;
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Updating app\u2026",
+        "App updated",
+        () => admin.updateApp(id, {
+          name: opts.name,
+          description: opts.description
+        })
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      console.log(`  ${green("\u2713")} Updated app ${app.name}`);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("networks <id>").description("Update app network allowlist").requiredOption("--networks <networks>", "Comma-separated network IDs").option("--dry-run", "Preview without executing").action(async (id, opts) => {
+    try {
+      const networks = splitCommaList(opts.networks);
+      if (handleDryRun(opts, "networks", { id, networks }, `Would update networks for app ${id}: ${networks.join(", ")}`)) return;
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Updating networks\u2026",
+        "Networks updated",
+        () => admin.updateNetworkAllowlist(id, networks)
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      console.log(
+        `  ${green("\u2713")} Updated networks for ${app.name} (${app.chainNetworks.length} networks)`
+      );
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("address-allowlist <id>").description("Update app address allowlist").requiredOption("--addresses <addrs>", "Comma-separated addresses").option("--dry-run", "Preview without executing").action(async (id, opts) => {
+    try {
+      const entries = splitCommaList(opts.addresses).map((s) => ({ value: s }));
+      if (handleDryRun(opts, "address-allowlist", { id, addresses: entries }, `Would update address allowlist for app ${id}`)) return;
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Updating address allowlist\u2026",
+        "Address allowlist updated",
+        () => admin.updateAddressAllowlist(id, entries)
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      console.log(
+        `  ${green("\u2713")} Updated address allowlist for ${app.name}`
+      );
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("origin-allowlist <id>").description("Update app origin allowlist").requiredOption("--origins <origins>", "Comma-separated origins").option("--dry-run", "Preview without executing").action(async (id, opts) => {
+    try {
+      const entries = splitCommaList(opts.origins).map((s) => ({ value: s }));
+      if (handleDryRun(opts, "origin-allowlist", { id, origins: entries }, `Would update origin allowlist for app ${id}`)) return;
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Updating origin allowlist\u2026",
+        "Origin allowlist updated",
+        () => admin.updateOriginAllowlist(id, entries)
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      console.log(
+        `  ${green("\u2713")} Updated origin allowlist for ${app.name}`
+      );
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("ip-allowlist <id>").description("Update app IP allowlist").requiredOption("--ips <ips>", "Comma-separated IP addresses").option("--dry-run", "Preview without executing").action(async (id, opts) => {
+    try {
+      const entries = splitCommaList(opts.ips).map((s) => ({ value: s }));
+      if (handleDryRun(opts, "ip-allowlist", { id, ips: entries }, `Would update IP allowlist for app ${id}`)) return;
+      const admin = adminClientFromFlags(program2);
+      const app = await withSpinner(
+        "Updating IP allowlist\u2026",
+        "IP allowlist updated",
+        () => admin.updateIpAllowlist(id, entries)
+      );
+      if (isJSONMode()) {
+        printJSON(maskAppSecrets(app));
+        return;
+      }
+      console.log(
+        `  ${green("\u2713")} Updated IP allowlist for ${app.name}`
+      );
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/setup.ts
+function registerSetup(program2) {
+  const cmd = program2.command("setup").description("Setup and onboarding utilities");
+  cmd.command("status").description("Show setup status and remediation commands").action(() => {
+    const status = getSetupStatus(load());
+    if (isJSONMode()) {
+      printJSON(status);
+      return;
+    }
+    printKeyValueBox([
+      ["Complete", status.complete ? "yes" : "no"],
+      ["Satisfied by", status.satisfiedBy ?? dim("(none)")]
+    ]);
+    if (status.missing.length > 0) {
+      console.log("");
+      console.log(`  ${dim("Missing:")}`);
+      for (const item of status.missing) {
+        console.log(`  ${dim(`- ${item}`)}`);
+      }
+    }
+    if (status.nextCommands.length > 0) {
+      console.log("");
+      console.log(`  ${dim("Next commands:")}`);
+      for (const command of status.nextCommands) {
+        console.log(`  ${dim(`- ${command}`)}`);
+      }
+    }
+  });
+}
+
+// src/lib/params.ts
+function parseCLIParams(params) {
+  return params.map((param) => {
+    try {
+      return JSON.parse(param);
+    } catch {
+      return param;
+    }
+  });
+}
+function parseRequiredJSON(input, label) {
+  try {
+    return JSON.parse(input);
+  } catch {
+    throw errInvalidArgs(`Invalid JSON for ${label}.`);
+  }
+}
+
+// src/commands/trace.ts
+function normalizeTraceMethod(method) {
+  if (method.startsWith("trace_")) return method;
+  const normalized = method.replace(/-/g, "_").toLowerCase();
+  if (normalized === "tx" || normalized === "transaction") {
+    return "trace_transaction";
+  }
+  return `trace_${normalized}`;
+}
+function registerTrace(program2) {
+  program2.command("trace <method> [params...]").description("Call a trace_* method").action(async (method, params) => {
+    try {
+      const client = clientFromFlags(program2);
+      const rpcMethod = normalizeTraceMethod(method);
+      const result = await withSpinner(
+        `Calling ${rpcMethod}\u2026`,
+        `Called ${rpcMethod}`,
+        () => client.call(rpcMethod, parseCLIParams(params))
+      );
+      printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/debug.ts
+function normalizeDebugMethod(method) {
+  if (method.startsWith("debug_")) return method;
+  return `debug_${method.replace(/-/g, "_")}`;
+}
+function registerDebug(program2) {
+  program2.command("debug <method> [params...]").description("Call a debug_* method").action(async (method, params) => {
+    try {
+      const client = clientFromFlags(program2);
+      const rpcMethod = normalizeDebugMethod(method);
+      const result = await withSpinner(
+        `Calling ${rpcMethod}\u2026`,
+        `Called ${rpcMethod}`,
+        () => client.call(rpcMethod, parseCLIParams(params))
+      );
+      printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/transfers.ts
+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) => {
+    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 = {
+        fromBlock: opts.fromBlock ?? "0x0",
+        toBlock: opts.toBlock ?? "latest",
+        withMetadata: true
+      };
+      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",
+        () => client.call("alchemy_getAssetTransfers", [filter])
+      );
+      if (isJSONMode()) {
+        printJSON(result);
+      } else {
+        printSyntaxJSON(result);
+      }
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/lib/rest.ts
+function withQuery(url, query) {
+  if (!query) return url;
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0 && value !== "") {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url;
+}
+async function requestJSON(url, options) {
+  const method = options.method ?? "GET";
+  const resp = await fetchWithTimeout(url.toString(), {
+    method,
+    headers: {
+      Accept: "application/json",
+      ...options.body !== void 0 ? { "Content-Type": "application/json" } : {},
+      ...options.extraHeaders ?? {}
+    },
+    ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+  });
+  if (resp.status === 429) throw errRateLimited();
+  if (resp.status === 401 || resp.status === 403) {
+    const detail = await resp.text().catch(() => "");
+    throw errInvalidAPIKey(detail || void 0);
+  }
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw errNetwork(`HTTP ${resp.status}: ${text}`);
+  }
+  return resp.json();
+}
+async function callApiData(apiKey, path, options = {}) {
+  if (!apiKey) throw errAuthRequired();
+  const base = new URL(`https://api.g.alchemy.com/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 url = withQuery(new URL(path.replace(/^\//, ""), base), options.query);
+  return requestJSON(url, { ...options, path });
+}
+async function callNotify(token, path, options = {}) {
+  if (!token) {
+    throw errInvalidArgs(
+      "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 url = withQuery(new URL(path.replace(/^\//, ""), base), options.query);
+  return requestJSON(url, {
+    ...options,
+    path,
+    extraHeaders: {
+      ...options.extraHeaders ?? {},
+      "X-Alchemy-Token": token
+    }
+  });
+}
+
+// src/commands/prices.ts
+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 result = await withSpinner(
+        "Fetching prices\u2026",
+        "Prices fetched",
+        () => callApiPrices(apiKey, `/tokens/by-symbol?${query.toString()}`)
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  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 result = await withSpinner(
+        "Fetching prices\u2026",
+        "Prices fetched",
+        () => callApiPrices(apiKey, "/tokens/by-address", { method: "POST", body })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("historical").description("Get historical prices").requiredOption("--body <json>", "JSON request payload").action(async (opts) => {
+    try {
+      const apiKey = resolveAPIKey(program2);
+      const payload = JSON.parse(opts.body);
+      const result = await withSpinner(
+        "Fetching historical prices\u2026",
+        "Historical prices fetched",
+        () => callApiPrices(apiKey, "/tokens/historical", { method: "POST", body: payload })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/portfolio.ts
+async function runDataCall(apiKey, title, path, body) {
+  return withSpinner(
+    `Fetching ${title}\u2026`,
+    `${title} fetched`,
+    () => callApiData(apiKey, 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,
+        "token portfolio",
+        "/assets/tokens/by-address",
+        JSON.parse(opts.body)
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  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,
+        "token balances",
+        "/assets/tokens/balances/by-address",
+        JSON.parse(opts.body)
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("nfts").description("Get NFT portfolio by address/network pairs").requiredOption("--body <json>", "JSON body for /assets/nfts/by-address").action(async (opts) => {
+    try {
+      const apiKey = resolveAPIKey(program2);
+      const result = await runDataCall(
+        apiKey,
+        "NFT portfolio",
+        "/assets/nfts/by-address",
+        JSON.parse(opts.body)
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  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,
+        "NFT contracts",
+        "/assets/nfts/contracts/by-address",
+        JSON.parse(opts.body)
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      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
+async function runSimulateCall(program2, options) {
+  const client = clientFromFlags(program2);
+  const result = await withSpinner(
+    `Calling ${options.method}\u2026`,
+    `Called ${options.method}`,
+    () => client.call(options.method, options.params)
+  );
+  printSyntaxJSON(result);
+}
+function registerSimulate(program2) {
+  const cmd = program2.command("simulate").description("Simulation API wrappers");
+  cmd.command("asset-changes").description("Call alchemy_simulateAssetChanges").requiredOption("--tx <json>", "Transaction object JSON").option("--block-tag <tag>", "Block tag (default latest)", "latest").action(async (opts) => {
+    try {
+      await runSimulateCall(program2, {
+        method: "alchemy_simulateAssetChanges",
+        params: [parseRequiredJSON(opts.tx, "--tx"), opts.blockTag]
+      });
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("execution").description("Call alchemy_simulateExecution").requiredOption("--tx <json>", "Transaction object JSON").option("--block-tag <tag>", "Block tag (default latest)", "latest").action(async (opts) => {
+    try {
+      await runSimulateCall(program2, {
+        method: "alchemy_simulateExecution",
+        params: [parseRequiredJSON(opts.tx, "--tx"), opts.blockTag]
+      });
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("asset-changes-bundle").description("Call alchemy_simulateAssetChangesBundle").requiredOption("--txs <json>", "JSON array of tx objects").option("--block-tag <tag>", "Block tag (default latest)", "latest").action(async (opts) => {
+    try {
+      await runSimulateCall(program2, {
+        method: "alchemy_simulateAssetChangesBundle",
+        params: [parseRequiredJSON(opts.txs, "--txs"), opts.blockTag]
+      });
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("execution-bundle").description("Call alchemy_simulateExecutionBundle").requiredOption("--txs <json>", "JSON array of tx objects").option("--block-tag <tag>", "Block tag (default latest)", "latest").action(async (opts) => {
+    try {
+      await runSimulateCall(program2, {
+        method: "alchemy_simulateExecutionBundle",
+        params: [parseRequiredJSON(opts.txs, "--txs"), opts.blockTag]
+      });
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/webhooks.ts
+function resolveWebhookApiKey(opts) {
+  const cfg = load();
+  return opts?.webhookApiKey || opts?.notifyToken || process.env.ALCHEMY_WEBHOOK_API_KEY || process.env.ALCHEMY_NOTIFY_AUTH_TOKEN || cfg.webhook_api_key || cfg.app?.webhookApiKey;
+}
+function registerWebhooks(program2) {
+  const cmd = program2.command("webhooks").description("Notify API wrappers");
+  cmd.option("--webhook-api-key <key>", "Webhook API key").option("--notify-token <token>", "Deprecated alias for webhook API key");
+  cmd.command("list").description("List team webhooks").action(async () => {
+    try {
+      const token = resolveWebhookApiKey(cmd.opts());
+      const result = await withSpinner(
+        "Fetching webhooks\u2026",
+        "Webhooks fetched",
+        () => callNotify(token, "/team-webhooks")
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("create").description("Create webhook").requiredOption("--body <json>", "Create webhook JSON payload").action(async (opts) => {
+    try {
+      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")
+        })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("update").description("Update webhook").requiredOption("--body <json>", "Update webhook JSON payload").action(async (opts) => {
+    try {
+      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")
+        })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("delete <webhookId>").description("Delete webhook").action(async (webhookId) => {
+    try {
+      const token = resolveWebhookApiKey(cmd.opts());
+      const result = await withSpinner(
+        "Deleting webhook\u2026",
+        "Webhook deleted",
+        () => callNotify(token, "/delete-webhook", {
+          method: "DELETE",
+          query: { webhook_id: webhookId }
+        })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("addresses <webhookId>").description("Get address activity webhook addresses").action(async (webhookId) => {
+    try {
+      const token = resolveWebhookApiKey(cmd.opts());
+      const result = await withSpinner(
+        "Fetching webhook addresses\u2026",
+        "Webhook addresses fetched",
+        () => callNotify(token, "/webhook-addresses", { query: { webhook_id: webhookId } })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("nft-filters <webhookId>").description("Get NFT activity webhook filters").action(async (webhookId) => {
+    try {
+      const token = resolveWebhookApiKey(cmd.opts());
+      const result = await withSpinner(
+        "Fetching NFT filters\u2026",
+        "NFT filters fetched",
+        () => callNotify(token, "/webhook-nft-filters", { query: { webhook_id: webhookId } })
+      );
+      if (isJSONMode()) printJSON(result);
+      else printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/bundler.ts
+async function runBundlerMethod(program2, method, params) {
+  const client = clientFromFlags(program2);
+  const result = await withSpinner(
+    `Calling ${method}\u2026`,
+    `Called ${method}`,
+    () => client.call(method, params)
+  );
+  printSyntaxJSON(result);
+}
+function registerBundler(program2) {
+  const cmd = program2.command("bundler").description("Wallet Bundler API wrappers");
+  cmd.command("send-user-operation").description("Call eth_sendUserOperation").requiredOption("--user-op <json>", "UserOperation JSON").requiredOption("--entry-point <address>", "EntryPoint address").action(async (opts) => {
+    try {
+      await runBundlerMethod(program2, "eth_sendUserOperation", [
+        parseRequiredJSON(opts.userOp, "--user-op"),
+        opts.entryPoint
+      ]);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("estimate-user-operation-gas").description("Call eth_estimateUserOperationGas").requiredOption("--user-op <json>", "UserOperation JSON").requiredOption("--entry-point <address>", "EntryPoint address").option("--state-override <json>", "State override set JSON").action(
+    async (opts) => {
+      try {
+        const params = [
+          parseRequiredJSON(opts.userOp, "--user-op"),
+          opts.entryPoint
+        ];
+        if (opts.stateOverride) {
+          params.push(parseRequiredJSON(opts.stateOverride, "--state-override"));
+        }
+        await runBundlerMethod(program2, "eth_estimateUserOperationGas", params);
+      } catch (err) {
+        exitWithError(err);
+      }
+    }
+  );
+  cmd.command("get-user-operation-receipt").description("Call eth_getUserOperationReceipt").requiredOption("--user-op-hash <hash>", "User operation hash").action(async (opts) => {
+    try {
+      await runBundlerMethod(program2, "eth_getUserOperationReceipt", [opts.userOpHash]);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/gas-manager.ts
+async function runGasMethod(program2, method, payload) {
+  const client = clientFromFlags(program2);
+  const result = await withSpinner(
+    `Calling ${method}\u2026`,
+    `Called ${method}`,
+    () => client.call(method, [payload])
+  );
+  printSyntaxJSON(result);
+}
+function registerGasManager(program2) {
+  const cmd = program2.command("gas-manager").description("Gas Manager API wrappers");
+  cmd.command("request-gas-and-paymaster").description("Call alchemy_requestGasAndPaymasterAndData").requiredOption("--body <json>", "Request payload JSON").action(async (opts) => {
+    try {
+      await runGasMethod(
+        program2,
+        "alchemy_requestGasAndPaymasterAndData",
+        parseRequiredJSON(opts.body, "--body")
+      );
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("request-paymaster-token-quote").description("Call alchemy_requestPaymasterTokenQuote").requiredOption("--body <json>", "Request payload JSON").action(async (opts) => {
+    try {
+      await runGasMethod(
+        program2,
+        "alchemy_requestPaymasterTokenQuote",
+        parseRequiredJSON(opts.body, "--body")
+      );
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/commands/solana.ts
+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 result = await withSpinner(
+        `Calling ${method}\u2026`,
+        `Called ${method}`,
+        () => client.call(method, parseCLIParams(params))
+      );
+      printSyntaxJSON(result);
+    } catch (err) {
+      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) => {
+    try {
+      const client = clientFromFlags(program2);
+      const result = await withSpinner(
+        `Calling ${method}\u2026`,
+        `Called ${method}`,
+        () => client.call(method, parseCLIParams(params))
+      );
+      printSyntaxJSON(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
+// src/index.ts
+var hBrand = noColor ? identity : (s) => `\x1B[38;2;54;63;249m${s}\x1B[39m`;
+var hBold = esc("1");
+var hDim = esc("2");
+var ROOT_OPTION_GROUPS = [
+  {
+    label: "Auth & Network",
+    matchers: ["--api-key", "--access-key", "--network", "--x402", "--wallet-key-file"]
+  },
+  {
+    label: "Output & Formatting",
+    matchers: ["--json", "--quiet", "--verbose", "--no-color", "--reveal"]
+  },
+  {
+    label: "Runtime & Behavior",
+    matchers: ["--timeout", "--debug", "--no-interactive"]
+  }
+];
+var ROOT_COMMAND_PILLARS = [
+  {
+    label: "Node",
+    commands: ["balance", "tx", "block", "rpc", "trace", "debug"]
+  },
+  {
+    label: "Data",
+    commands: ["tokens", "nfts", "transfers", "prices", "portfolio", "simulate"]
+  },
+  {
+    label: "Wallets",
+    commands: ["wallet", "bundler", "gas-manager", "webhooks"]
+  },
+  {
+    label: "Chains",
+    commands: ["network", "chains", "solana"]
+  },
+  {
+    label: "Admin",
+    commands: ["apps", "config", "setup", "version", "help"]
+  }
+];
+function formatCommandSignature(sub) {
+  const args = sub.registeredArguments.map((arg) => {
+    const variadic = arg.variadic === true;
+    const name = variadic ? `${arg.name()}...` : arg.name();
+    return arg.required ? `<${name}>` : `[${name}]`;
+  });
+  return [sub.name(), ...args].join(" ");
+}
+function rootOptionGroupLabel(flags) {
+  for (const group of ROOT_OPTION_GROUPS) {
+    if (group.matchers.some((matcher) => flags.includes(matcher))) {
+      return group.label;
+    }
+  }
+  return "General";
+}
+var program = new Command();
+var argvTokens = process.argv.slice(2);
+var isHelpInvocation = argvTokens.some(
+  (token) => token === "help" || token === "--help" || token === "-h"
+);
+var findCommandByPath = (root, path) => {
+  let current = root;
+  for (const segment of path) {
+    const next = current.commands.find(
+      (cmd) => cmd.name() === segment || cmd.aliases().includes(segment)
+    );
+    if (!next) return null;
+    current = next;
+  }
+  return current;
+};
+program.name("alchemy").description(
+  "The Alchemy CLI lets you query blockchain data, call JSON-RPC methods, and manage your Alchemy configuration."
+).version("0.1.0").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("-v, --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).configureOutput({
+  outputError(str, write) {
+    write(formatCommanderError(str));
+  }
+}).configureHelp({
+  formatHelp(cmd, helper) {
+    const defaultHelp = Help.prototype.formatHelp.call(helper, cmd, helper);
+    if (isJSONMode()) {
+      const schema = {
+        name: cmd.name(),
+        description: cmd.description()
+      };
+      const args = cmd.registeredArguments;
+      if (args.length > 0) {
+        schema.arguments = args.map((a) => ({
+          name: a.name(),
+          description: a.description,
+          required: a.required
+        }));
+      }
+      const opts = cmd.options;
+      if (opts.length > 0) {
+        schema.options = opts.map((o) => ({
+          flags: o.flags,
+          description: o.description
+        }));
+      }
+      const subs = cmd.commands;
+      if (subs.length > 0) {
+        schema.subcommands = subs.map((s) => ({
+          name: s.name(),
+          description: s.description()
+        }));
+      }
+      return JSON.stringify(schema, null, 2) + "\n";
+    }
+    const lines = defaultHelp.split("\n");
+    let section = null;
+    const emittedOptionGroups = /* @__PURE__ */ new Set();
+    const out = lines.map((line) => {
+      const sectionMatch = line.match(/^(Usage|Commands|Options|Arguments):$/);
+      if (sectionMatch) {
+        const title = sectionMatch[1];
+        if (title === "Commands" && cmd === program) {
+          section = "commands";
+          const byName = new Map(
+            cmd.commands.map((sub) => [sub.name(), sub])
+          );
+          const groupedRows = ROOT_COMMAND_PILLARS.map((pillar) => {
+            const rows = pillar.commands.map((name) => byName.get(name)).filter((sub) => Boolean(sub)).map((sub) => ({
+              left: formatCommandSignature(sub),
+              right: sub.description()
+            }));
+            return { label: pillar.label, rows };
+          }).filter((group) => group.rows.length > 0);
+          const maxLeft = Math.max(
+            0,
+            ...groupedRows.flatMap((group) => group.rows.map((row) => row.left.length))
+          );
+          const groupText = groupedRows.map((group) => {
+            const header = `  ${hBold(group.label)}${hDim(":")}`;
+            const rows = group.rows.map((row) => {
+              const gap = " ".repeat(Math.max(2, maxLeft - row.left.length + 2));
+              return `    ${hBrand(row.left)}${gap}${hDim(row.right)}`;
+            }).join("\n");
+            return `${header}
+${rows}`;
+          }).join("\n\n");
+          return `${hBrand("\u25C6")} ${hBold("Commands")}
+  ${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")}
+${groupText}`;
+        }
+        section = title.toLowerCase();
+        return `${hBrand("\u25C6")} ${hBold(title)}
+  ${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")}`;
+      }
+      if (line.trim() === "") {
+        section = null;
+        return line;
+      }
+      if (section === "commands" && cmd === program) {
+        return null;
+      }
+      if (section === "options" || section === "commands") {
+        const entryMatch = line.match(/^(\s+)(.+?)(\s{2,})(.+)$/);
+        if (entryMatch) {
+          const [, indent, left, gap, right] = entryMatch;
+          const styledLine = `${indent}${hBrand(left)}${gap}${hDim(right)}`;
+          if (section === "options" && cmd === program) {
+            const groupLabel = rootOptionGroupLabel(left);
+            if (!emittedOptionGroups.has(groupLabel)) {
+              emittedOptionGroups.add(groupLabel);
+              const needsLeadingGap = emittedOptionGroups.size > 1;
+              const groupHeader = `${indent}${hBold(groupLabel)}${hDim(":")}`;
+              return `${needsLeadingGap ? "\n" : ""}${groupHeader}
+${styledLine}`;
+            }
+          }
+          return styledLine;
+        }
+      }
+      return line;
+    }).filter((line) => line !== null);
+    return out.join("\n") + "\n";
+  }
+}).addHelpText("beforeAll", () => isHelpInvocation ? brandedHelp() : "").addHelpText("after", () => {
+  if (isJSONMode()) return "";
+  return [
+    "",
+    `${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")}`,
+    `  ${hBrand("0")}     Success`,
+    `  ${hBrand("1")}     Internal error`,
+    `  ${hBrand("2")}     Invalid arguments`,
+    `  ${hBrand("3")}     Authentication required`,
+    `  ${hBrand("4")}     Not found`,
+    `  ${hBrand("5")}     Rate limited`,
+    `  ${hBrand("6")}     Network error`,
+    `  ${hBrand("7")}     RPC error`,
+    `  ${hBrand("8")}     Admin API error`,
+    `  ${hBrand("9")}     Payment required`,
+    `  ${hBrand("130")}   Interrupted (SIGINT)`,
+    "",
+    `${hBrand("\u25C6")} ${hBold("Resources")}`,
+    `  ${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")}`,
+    `  ${hDim("Docs:")} ${hBrand("https://www.alchemy.com/docs")}`
+  ].join("\n");
+}).hook("preAction", () => {
+  const opts = program.opts();
+  const cfg = load();
+  setFlags({
+    json: opts.json,
+    quiet: opts.quiet,
+    verbose: Boolean(opts.verbose || cfg.verbose),
+    debug: Boolean(opts.debug),
+    reveal: Boolean(opts.reveal),
+    timeout: opts.timeout
+  });
+}).hook("postAction", () => {
+  if (!isJSONMode() && !quiet) {
+    console.log("");
+  }
+}).action(async () => {
+  const cfg = load();
+  if (!isSetupComplete(cfg) && !isInteractiveAllowed(program)) {
+    throw errSetupRequired(getSetupStatus(cfg));
+  }
+  if (isInteractiveAllowed(program)) {
+    if (shouldRunOnboarding(program, cfg)) {
+      const { runOnboarding } = await import("./onboarding-3J4EXZMG.js");
+      const completed = await runOnboarding(program);
+      if (!completed) {
+        return;
+      }
+    }
+    const { startREPL } = await import("./interactive-2ITFWH3B.js");
+    program.exitOverride();
+    program.configureOutput({
+      writeErr: () => {
+      }
+    });
+    await startREPL(program);
+    return;
+  }
+  program.help();
+});
+registerRPC(program);
+registerBalance(program);
+registerTx(program);
+registerBlock(program);
+registerTrace(program);
+registerDebug(program);
+registerTokens(program);
+registerNFTs(program);
+registerTransfers(program);
+registerPrices(program);
+registerPortfolio(program);
+registerSimulate(program);
+registerWallet(program);
+registerBundler(program);
+registerGasManager(program);
+registerWebhooks(program);
+registerNetwork(program);
+registerChains(program);
+registerApps(program);
+registerSetup(program);
+registerConfig(program);
+registerSolana(program);
+registerVersion(program);
+program.command("help [command...]").description("display help for command").action((commandPath) => {
+  if (!commandPath || commandPath.length === 0) {
+    program.outputHelp();
+    return;
+  }
+  const target = findCommandByPath(program, commandPath);
+  if (!target) {
+    program.error(`unknown command '${commandPath.join(" ")}'`);
+    return;
+  }
+  target.outputHelp();
+});
+process.on("unhandledRejection", (err) => exitWithError(err));
+process.on("uncaughtException", (err) => exitWithError(err));
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => {
+  if (!isJSONMode()) process.stderr.write("\nInterrupted.\n");
+  process.exit(130);
+});
+program.parse();