@alchemy/cli 0.2.1 → 0.2.2

package/dist/{chunk-SDUCDSCZ.js → chunk-2WI4JODY.js}

@@ -326,8 +326,16 @@ function errNetwork(detail) {
     "Check your internet connection and try again."
   );
 }
+var RPC_ERROR_HINTS = {
+  [-32700]: "Parse error. The request JSON is malformed.",
+  [-32600]: "Invalid request. Check the JSON-RPC request format.",
+  [-32601]: "Method not supported. Check the method name and ensure your plan supports it.",
+  [-32602]: "Invalid parameters. Check argument types and format.",
+  [-32603]: "Internal JSON-RPC error."
+};
 function errRPC(code, message) {
-  return new CLIError(ErrorCode.RPC_ERROR, `RPC error ${code}: ${message}`);
+  const hint = RPC_ERROR_HINTS[code];
+  return new CLIError(ErrorCode.RPC_ERROR, `RPC error ${code}: ${message}`, hint);
 }
 function errInvalidArgs(detail) {
   return new CLIError(ErrorCode.INVALID_ARGS, detail);
@@ -349,6 +357,14 @@ function errInvalidAccessKey() {
     "Get an access key: https://www.alchemy.com/docs/reference/admin-api/overview"
   );
 }
+function errAccessDenied(detail) {
+  const message = detail ? `Access denied: ${detail}` : "Access denied. Your access key may not have permission for this operation.";
+  return new CLIError(
+    ErrorCode.INVALID_ACCESS_KEY,
+    message,
+    "Check your account tier and feature access at https://dashboard.alchemy.com/"
+  );
+}
 function errAppRequired() {
   return new CLIError(
     ErrorCode.APP_REQUIRED,
@@ -1093,7 +1109,7 @@ function semverLT(a, b) {
   return false;
 }
 function currentVersion() {
-  return true ? "0.2.1" : "0.0.0";
+  return true ? "0.2.2" : "0.0.0";
 }
 function toUpdateStatus(latestVersion, checkedAt) {
   const current = currentVersion();
@@ -1178,6 +1194,7 @@ export {
   errNotFound,
   errRateLimited,
   errInvalidAccessKey,
+  errAccessDenied,
   errAppRequired,
   errWalletKeyRequired,
   errAdminAPI,

package/dist/{chunk-XP5KF4W2.js → chunk-6KOJKH6N.js}

@@ -7,6 +7,7 @@ import {
   configDir,
   debug,
   dim,
+  errAccessDenied,
   errAccessKeyRequired,
   errAdminAPI,
   errAppRequired,
@@ -40,7 +41,7 @@ import {
   toMap,
   withSpinner,
   yellow
-} from "./chunk-SDUCDSCZ.js";
+} from "./chunk-2WI4JODY.js";
 
 // src/lib/client-utils.ts
 function isLocalhost(hostname) {
@@ -82,7 +83,24 @@ async function fetchWithTimeout(url, init) {
     if (err instanceof DOMException && err.name === "TimeoutError") {
       throw errNetwork(`Request timed out after ${timeout}ms`);
     }
-    throw errNetwork(err.message);
+    const message = err.message ?? String(err);
+    const causeMessage = err.cause?.message ?? "";
+    const causeCode = err.cause?.code ?? "";
+    const fullErrorText = `${message} ${causeMessage} ${causeCode}`;
+    if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(fullErrorText)) {
+      try {
+        const hostname = new URL(url).hostname;
+        const networkSlug = hostname.replace(/\.g\.alchemy\.com$/, "");
+        if (networkSlug !== hostname) {
+          throw errInvalidArgs(
+            `Unknown network '${networkSlug}'. Run 'alchemy network list' to see available networks.`
+          );
+        }
+      } catch (innerErr) {
+        if (innerErr instanceof CLIError) throw innerErr;
+      }
+    }
+    throw errNetwork(message);
   }
 }
 
@@ -145,7 +163,18 @@ var AdminClient = class _AdminClient {
       },
       ...body !== void 0 && { body: JSON.stringify(body) }
     });
-    if (resp.status === 401 || resp.status === 403) throw errInvalidAccessKey();
+    if (resp.status === 401) throw errInvalidAccessKey();
+    if (resp.status === 403) {
+      const detail = await resp.text().catch(() => "");
+      let reason;
+      try {
+        const parsed = JSON.parse(detail);
+        reason = parsed?.message || parsed?.error?.message || parsed?.error || void 0;
+      } catch {
+        reason = detail || void 0;
+      }
+      throw errAccessDenied(typeof reason === "string" ? reason : void 0);
+    }
     if (resp.status === 404) {
       const text = await resp.text().catch(() => "");
       throw errNotFound(text || path);
@@ -686,10 +715,14 @@ var Client = class _Client {
     try {
       parsed = new URL(`https://${hostname}`);
     } catch {
-      throw errInvalidArgs(`Invalid network: ${network}`);
+      throw errInvalidArgs(
+        `Unknown network '${network}'. Run 'alchemy network list' to see available networks.`
+      );
     }
     if (!parsed.hostname.endsWith(".g.alchemy.com")) {
-      throw errInvalidArgs(`Invalid network: ${network} \u2014 hostname must end with .g.alchemy.com`);
+      throw errInvalidArgs(
+        `Unknown network '${network}'. Run 'alchemy network list' to see available networks.`
+      );
     }
   }
   rpcBaseURLOverride() {
@@ -718,6 +751,16 @@ var Client = class _Client {
     if (networkNotEnabled) return networkNotEnabled;
     return errInvalidAPIKey(detail || void 0);
   }
+  tryParseRPCError(text) {
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed?.error?.code !== void 0 && parsed?.error?.message !== void 0) {
+        return errRPC(parsed.error.code, parsed.error.message);
+      }
+    } catch {
+    }
+    return null;
+  }
   async doFetch(url, init) {
     return fetchWithTimeout(url, init);
   }
@@ -743,6 +786,8 @@ var Client = class _Client {
     }
     if (!resp.ok) {
       const text = await resp.text().catch(() => "");
+      const rpcError = this.tryParseRPCError(text);
+      if (rpcError) throw rpcError;
       throw errNetwork(`HTTP ${resp.status}: ${text}`);
     }
     const rpcResp = await resp.json();
@@ -766,6 +811,8 @@ var Client = class _Client {
     }
     if (!resp.ok) {
       const text = await resp.text().catch(() => "");
+      const rpcError = this.tryParseRPCError(text);
+      if (rpcError) throw rpcError;
       throw errNetwork(`HTTP ${resp.status}: ${text}`);
     }
     return resp.json();

package/dist/{chunk-HBRTTBCY.js → chunk-NA7MQB7X.js}

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

package/dist/index.js

@@ -14,13 +14,13 @@ import {
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-XP5KF4W2.js";
+} from "./chunk-6KOJKH6N.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-HBRTTBCY.js";
+} from "./chunk-NA7MQB7X.js";
 import {
   EXIT_CODES,
   ErrorCode,
@@ -65,7 +65,7 @@ import {
   verbose,
   weiToEth,
   withSpinner
-} from "./chunk-SDUCDSCZ.js";
+} from "./chunk-2WI4JODY.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -277,6 +277,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);
@@ -1912,10 +1915,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.2.2", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option("--access-key <key>", "Alchemy access key (env: ALCHEMY_ACCESS_KEY)").option(
   "-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").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);
   }
@@ -2067,7 +2070,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 +2086,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-YA32OJOT.js");
+      const { runOnboarding } = await import("./onboarding-SJ2BRK5I.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -2087,7 +2098,7 @@ ${styledLine}`;
       latestForInteractiveStartup = getAvailableUpdateOnce();
       updateShownDuringInteractiveStartup = Boolean(latestForInteractiveStartup);
     }
-    const { startREPL } = await import("./interactive-L7N4HI7K.js");
+    const { startREPL } = await import("./interactive-EAUEVR63.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {

package/dist/{interactive-L7N4HI7K.js → interactive-EAUEVR63.js}

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

package/dist/{onboarding-YA32OJOT.js → onboarding-SJ2BRK5I.js}

@@ -5,7 +5,7 @@ import {
   generateAndPersistWallet,
   importAndPersistWallet,
   selectOrCreateApp
-} from "./chunk-XP5KF4W2.js";
+} from "./chunk-6KOJKH6N.js";
 import {
   bold,
   brand,
@@ -19,7 +19,7 @@ import {
   promptSelect,
   promptText,
   save
-} from "./chunk-SDUCDSCZ.js";
+} from "./chunk-2WI4JODY.js";
 
 // src/commands/onboarding.ts
 function printNextSteps(method) {

package/package.json

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