@alchemy/cli 0.13.0 → 0.14.0

package/dist/{auth-5XFZB2BU.js → auth-57YPPTNF.js}

@@ -11,8 +11,8 @@ import {
   prepareLogin,
   revokeToken,
   waitForCallback
-} from "./chunk-I6YQX7PF.js";
-import "./chunk-5BEJA752.js";
+} from "./chunk-CZWKHYTE.js";
+import "./chunk-CFIDLPKB.js";
 export {
   AUTH_PORT,
   DEFAULT_EXPIRES_IN_SECONDS,

package/dist/auth-ZBEPAFEP.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
+import {
+  registerAuth,
+  selectAppAfterAuth
+} from "./chunk-WDGPT4OT.js";
+import "./chunk-CZWKHYTE.js";
+import "./chunk-EJB4WDTU.js";
+import "./chunk-CXR7CCJ7.js";
+import "./chunk-OIRERSZT.js";
+import "./chunk-PISUI34T.js";
+import "./chunk-CFIDLPKB.js";
+export {
+  registerAuth,
+  selectAppAfterAuth
+};

package/dist/{chunk-OE6B6S2H.js → chunk-22KBYYLI.js}

@@ -2,10 +2,10 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   configPath
-} from "./chunk-LANOFNO6.js";
+} from "./chunk-PISUI34T.js";
 import {
   esc
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/update-check.ts
 import { execFileSync } from "child_process";
@@ -53,7 +53,7 @@ function semverLT(a, b) {
   return false;
 }
 function currentVersion() {
-  return true ? "0.13.0" : "0.0.0";
+  return true ? "0.14.0" : "0.0.0";
 }
 function toUpdateStatus(latestVersion, checkedAt) {
   const current = currentVersion();

package/dist/{chunk-5BEJA752.js → chunk-CFIDLPKB.js}

@@ -301,6 +301,7 @@ var ErrorCode = {
   PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
   SETUP_REQUIRED: "SETUP_REQUIRED",
   QUOTE_FAILED: "QUOTE_FAILED",
+  PREFLIGHT_REVERT: "PREFLIGHT_REVERT",
   INTERNAL_ERROR: "INTERNAL_ERROR"
 };
 var RETRYABLE_CODES = /* @__PURE__ */ new Set([
@@ -321,6 +322,7 @@ var EXIT_CODES = {
   PAYMENT_REQUIRED: 9,
   SETUP_REQUIRED: 3,
   QUOTE_FAILED: 10,
+  PREFLIGHT_REVERT: 11,
   INTERNAL_ERROR: 1
 };
 var CLIError = class extends Error {
@@ -414,6 +416,15 @@ function errRPC(code, message) {
 function errInvalidArgs(detail) {
   return new CLIError(ErrorCode.INVALID_ARGS, detail);
 }
+function errPreflightRevert(reason, details) {
+  return new CLIError(
+    ErrorCode.PREFLIGHT_REVERT,
+    `Transaction preflight reverted: ${reason}`,
+    "Fix the revert reason, lower the amount, adjust allowance/balance, or try a dry run before submitting again.",
+    details,
+    { reason }
+  );
+}
 function errNotFound(resource) {
   return new CLIError(ErrorCode.NOT_FOUND, `Not found: ${resource}`);
 }
@@ -549,6 +560,7 @@ export {
   errNetworkRequired,
   errRPC,
   errInvalidArgs,
+  errPreflightRevert,
   errNotFound,
   errRateLimited,
   errAccessDenied,

package/dist/{chunk-PRSZJXA6.js → chunk-CXR7CCJ7.js}

@@ -4,7 +4,7 @@ import {
   configDir,
   load,
   save
-} from "./chunk-LANOFNO6.js";
+} from "./chunk-PISUI34T.js";
 import {
   CLIError,
   ErrorCode,
@@ -30,7 +30,7 @@ import {
   redactSensitiveText,
   timeout,
   verbose
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/resolve.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -1272,8 +1272,10 @@ var walletSessionCapabilitiesSchema = z.object({
   "evm.signMessage": z.boolean().optional(),
   "evm.signTypedData": z.boolean().optional(),
   "evm.signAuthorization": z.boolean().optional(),
+  "evm.prepareCalls": z.boolean().optional(),
+  "evm.sendCalls": z.boolean().optional(),
   "solana.signTransaction": z.boolean().optional()
-}).strict();
+}).catchall(z.boolean());
 var walletSessionEnvironmentSchema = z.object({
   platform: z.string().min(1),
   arch: z.string().min(1),
@@ -1320,6 +1322,42 @@ var walletSessionSchema = z.object({
     solana: chainWalletSessionSchema.optional()
   }).strict().optional()
 }).strict();
+var LEGACY_PERSISTED_CAPABILITY_KEYS = [
+  "evm.signMessage",
+  "evm.signTypedData",
+  "evm.signAuthorization",
+  "solana.signTransaction"
+];
+function persistedCapabilities(capabilities) {
+  if (!capabilities) return void 0;
+  const persisted = {};
+  for (const key of LEGACY_PERSISTED_CAPABILITY_KEYS) {
+    const value = capabilities[key];
+    if (value !== void 0) {
+      persisted[key] = value;
+    }
+  }
+  return Object.keys(persisted).length > 0 ? persisted : void 0;
+}
+function withPersistedChainCapabilities(chainSession) {
+  const { capabilities, ...rest } = chainSession;
+  const persisted = persistedCapabilities(capabilities);
+  return persisted ? { ...rest, capabilities: persisted } : rest;
+}
+function toPersistedSession(session) {
+  const aliased = withCompatibilityAliases(session);
+  const { capabilities, sessionsByChain, ...rest } = aliased;
+  const persistedCapabilitiesForSession = persistedCapabilities(capabilities);
+  const persistedSessionsByChain = sessionsByChain ? {
+    ...sessionsByChain.evm ? { evm: withPersistedChainCapabilities(sessionsByChain.evm) } : {},
+    ...sessionsByChain.solana ? { solana: withPersistedChainCapabilities(sessionsByChain.solana) } : {}
+  } : void 0;
+  return {
+    ...rest,
+    ...persistedCapabilitiesForSession ? { capabilities: persistedCapabilitiesForSession } : {},
+    ...persistedSessionsByChain ? { sessionsByChain: persistedSessionsByChain } : {}
+  };
+}
 function sessionPath() {
   return join(configDir(), SESSION_FILE);
 }
@@ -1475,7 +1513,7 @@ function loadStoredSession() {
   return store.load();
 }
 function saveSession(session) {
-  getWalletSessionStore().save(withCompatibilityAliases(session));
+  getWalletSessionStore().save(toPersistedSession(session));
 }
 function updateSession(updates) {
   const session = loadSession();

package/dist/{chunk-I6YQX7PF.js → chunk-CZWKHYTE.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getBaseDomain
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/auth.ts
 import { createHash, randomBytes } from "crypto";

package/dist/{chunk-RPSHRYCZ.js → chunk-EJB4WDTU.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isJSONMode
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/interaction.ts
 import { stdin, stdout } from "process";

package/dist/{chunk-PYIVNQEI.js → chunk-M7HFRKW6.js}

@@ -3,7 +3,7 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   gasManagerClientFromFlags,
   toAdminNetworkId
-} from "./chunk-PRSZJXA6.js";
+} from "./chunk-CXR7CCJ7.js";
 import {
   dim,
   green,
@@ -11,16 +11,16 @@ import {
   promptConfirm,
   promptText,
   withSpinner
-} from "./chunk-DXQAGBW6.js";
+} from "./chunk-OIRERSZT.js";
 import {
   load,
   save
-} from "./chunk-LANOFNO6.js";
+} from "./chunk-PISUI34T.js";
 import {
   errAppRequired,
   errInvalidArgs,
   errLoginRequired
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/policy-prompt.ts
 var CREATE_NEW_SENTINEL = "__create_new__";

package/dist/{chunk-DXQAGBW6.js → chunk-OIRERSZT.js}

@@ -5,7 +5,7 @@ import {
   isJSONMode,
   quiet,
   rgb
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/terminal-ui.ts
 import * as readline from "readline";

package/dist/{chunk-LANOFNO6.js → chunk-PISUI34T.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isRevealMode
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/lib/secrets.ts
 function maskSecret(value) {

package/dist/{chunk-DWNXGFON.js → chunk-RQDWIB62.js}

@@ -2,11 +2,11 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isInteractiveAllowed
-} from "./chunk-RPSHRYCZ.js";
+} from "./chunk-EJB4WDTU.js";
 import {
   resolveAuthToken,
   resolveWalletSession
-} from "./chunk-PRSZJXA6.js";
+} from "./chunk-CXR7CCJ7.js";
 
 // src/lib/onboarding.ts
 var SETUP_CAPABILITY_ORDER = [

package/dist/{chunk-5DR7BHUX.js → chunk-WDGPT4OT.js}

@@ -4,14 +4,14 @@ import {
   completeLogin,
   prepareLogin,
   revokeToken
-} from "./chunk-I6YQX7PF.js";
+} from "./chunk-CZWKHYTE.js";
 import {
   isInteractiveAllowed
-} from "./chunk-RPSHRYCZ.js";
+} from "./chunk-EJB4WDTU.js";
 import {
   AdminClient,
   resolveAuthToken
-} from "./chunk-PRSZJXA6.js";
+} from "./chunk-CXR7CCJ7.js";
 import {
   bold,
   brand,
@@ -20,13 +20,13 @@ import {
   promptAutocomplete,
   promptText,
   withSpinner
-} from "./chunk-DXQAGBW6.js";
+} from "./chunk-OIRERSZT.js";
 import {
   configPath,
   load,
   maskIf,
   save
-} from "./chunk-LANOFNO6.js";
+} from "./chunk-PISUI34T.js";
 import {
   CLIError,
   ErrorCode,
@@ -34,7 +34,7 @@ import {
   exitWithError,
   isJSONMode,
   printHuman
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/commands/auth.ts
 function registerAuth(program) {

package/dist/{errors-6BEPCY5N.js → errors-VS7SGW7B.js}

@@ -16,6 +16,7 @@ import {
   errNetworkRequired,
   errNoActiveSession,
   errNotFound,
+  errPreflightRevert,
   errRPC,
   errRateLimited,
   errSessionExpired,
@@ -27,7 +28,7 @@ import {
   exitWithError,
   isReplMode,
   setReplMode
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 export {
   CLIError,
   EXIT_CODES,
@@ -44,6 +45,7 @@ export {
   errNetworkRequired,
   errNoActiveSession,
   errNotFound,
+  errPreflightRevert,
   errRPC,
   errRateLimited,
   errSessionExpired,

package/dist/index.js

@@ -5,23 +5,23 @@ import {
   errNotLoggedInForPolicyLookup,
   errSponsorshipNeedsPolicy,
   selectOrCreatePolicy
-} from "./chunk-PYIVNQEI.js";
+} from "./chunk-M7HFRKW6.js";
 import {
   registerAuth
-} from "./chunk-5DR7BHUX.js";
+} from "./chunk-WDGPT4OT.js";
 import {
   openBrowser
-} from "./chunk-I6YQX7PF.js";
+} from "./chunk-CZWKHYTE.js";
 import {
   SETUP_CAPABILITY_LABELS,
   SETUP_CAPABILITY_ORDER,
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-DWNXGFON.js";
+} from "./chunk-RQDWIB62.js";
 import {
   isInteractiveAllowed
-} from "./chunk-RPSHRYCZ.js";
+} from "./chunk-EJB4WDTU.js";
 import {
   RpcApiError,
   adminClientFromFlags,
@@ -63,12 +63,12 @@ import {
   updateSession,
   validateNetwork,
   walletNetworkToChain
-} from "./chunk-PRSZJXA6.js";
+} from "./chunk-CXR7CCJ7.js";
 import {
   getAvailableUpdate,
   getUpdateStatus,
   printUpdateNotice
-} from "./chunk-OE6B6S2H.js";
+} from "./chunk-22KBYYLI.js";
 import {
   bold,
   brand,
@@ -92,7 +92,7 @@ import {
   weiToEth,
   withSpinner,
   yellow
-} from "./chunk-DXQAGBW6.js";
+} from "./chunk-OIRERSZT.js";
 import {
   KEY_MAP,
   configDir,
@@ -103,7 +103,7 @@ import {
   save,
   toMap,
   validKeys
-} from "./chunk-LANOFNO6.js";
+} from "./chunk-PISUI34T.js";
 import {
   CLIError,
   EXIT_CODES,
@@ -116,6 +116,7 @@ import {
   errNetwork,
   errNoActiveSession,
   errNotFound,
+  errPreflightRevert,
   errRPC,
   errRateLimited,
   errSessionExpired,
@@ -144,7 +145,7 @@ import {
   setNoColor,
   timeout,
   verbose
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -581,8 +582,8 @@ function registerConfig(program2) {
           "Interactive policy selection requires an interactive terminal. Pass an ID: `alchemy config set evm-gas-policy-id <id>`."
         );
       }
-      const { selectOrCreatePolicy: selectOrCreatePolicy2 } = await import("./policy-prompt-LY6DMMT4.js");
-      const { resolveNetwork: resolveNetwork2 } = await import("./resolve-GELBKDTP.js");
+      const { selectOrCreatePolicy: selectOrCreatePolicy2 } = await import("./policy-prompt-UNNIF63S.js");
+      const { resolveNetwork: resolveNetwork2 } = await import("./resolve-IRTGQL4A.js");
       const network = resolveNetwork2(program2);
       await selectOrCreatePolicy2({
         flavor: "sponsorship",
@@ -636,8 +637,8 @@ function registerConfig(program2) {
           "Interactive policy selection requires an interactive terminal. Pass an ID: `alchemy config set solana-fee-policy-id <id>`."
         );
       }
-      const { selectOrCreatePolicy: selectOrCreatePolicy2 } = await import("./policy-prompt-LY6DMMT4.js");
-      const { resolveSolanaNetwork: resolveSolanaNetwork2 } = await import("./resolve-GELBKDTP.js");
+      const { selectOrCreatePolicy: selectOrCreatePolicy2 } = await import("./policy-prompt-UNNIF63S.js");
+      const { resolveSolanaNetwork: resolveSolanaNetwork2 } = await import("./resolve-IRTGQL4A.js");
       const network = resolveSolanaNetwork2(program2);
       await selectOrCreatePolicy2({
         flavor: "solana",
@@ -694,7 +695,7 @@ function registerConfig(program2) {
       printJSON(toMap(cfg));
       return;
     }
-    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-GELBKDTP.js");
+    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-IRTGQL4A.js");
     const validToken = resolveAuthToken2(cfg);
     const authStatus = cfg.auth_token ? validToken ? `${green("\u2713")} authenticated${cfg.auth_token_expires_at ? ` ${dim(`(expires ${cfg.auth_token_expires_at})`)}` : ""}` : `${yellow("\u25C6")} expired${cfg.auth_token_expires_at ? ` ${dim(`(${cfg.auth_token_expires_at})`)}` : ""}` : dim("(not set) \u2014 run 'alchemy auth' to log in");
     const pairs = [
@@ -1880,7 +1881,9 @@ var CONNECT_TIMEOUT_MS = 5 * 6e4;
 var DEFAULT_WALLET_CAPABILITIES = {
   "evm.signMessage": true,
   "evm.signTypedData": true,
-  "evm.signAuthorization": true
+  "evm.signAuthorization": true,
+  "evm.prepareCalls": true,
+  "evm.sendCalls": true
 };
 var DEFAULT_SOLANA_SESSION_CAPABILITIES = {
   "solana.signTransaction": true
@@ -2060,6 +2063,30 @@ function formatWalletStatus(value) {
   if (value === "active") return green("active");
   return dim(value);
 }
+function walletModeSummary(args) {
+  return {
+    session: {
+      available: args.sessionActive,
+      signing: "delegated session approval",
+      transactionSupport: ["wallet_prepareCalls", "wallet_sendCalls"],
+      preflightSimulation: true,
+      sponsorshipEligible: true,
+      nonceManagement: "Alchemy smart wallet",
+      supportedCallShapes: ["single call", "batch calls", "paymaster capabilities"]
+    },
+    local: {
+      available: args.localEvmConfigured || args.localSolanaConfigured,
+      evmConfigured: args.localEvmConfigured,
+      solanaConfigured: args.localSolanaConfigured,
+      signing: "local private key",
+      transactionSupport: ["wallet_sendCalls for EVM smart-wallet commands", "Solana transaction signing"],
+      preflightSimulation: false,
+      sponsorshipEligible: true,
+      nonceManagement: "local signer / chain-specific client",
+      supportedCallShapes: ["single call", "batch calls when routed through EVM smart-wallet commands"]
+    }
+  };
+}
 function walletKeysDirPath() {
   return join(configDir(), WALLET_KEYS_DIR);
 }
@@ -2786,6 +2813,11 @@ function registerWallets(program2) {
         Boolean(localState.evmAddress)
       );
       if (isJSONMode()) {
+        const modes = walletModeSummary({
+          sessionActive: snap.status === "active",
+          localEvmConfigured: Boolean(localState.evmAddress),
+          localSolanaConfigured: Boolean(localSolanaAddress)
+        });
         printJSON({
           // Preserved top-level fields (session-scoped, backward-compatible).
           walletAddress: snap.walletAddress,
@@ -2819,7 +2851,8 @@ function registerWallets(program2) {
           },
           localEvm: localState.evmAddress ? { address: localState.evmAddress, keyFile: localState.evmKeyFile } : null,
           localSolana: localSolanaAddress ? { address: localSolanaAddress, keyFile: localState.solanaKeyFile } : null,
-          activeSigner
+          activeSigner,
+          modes
         });
         return;
       }
@@ -2830,7 +2863,9 @@ function registerWallets(program2) {
         ["Local EVM", localState.evmAddress ?? dim("not configured")],
         ["Local Solana", localSolanaAddress ?? dim("not configured")],
         ["Environment", snap.environment ?? dim("none")],
-        ["Signer Capabilities", snap.signerCapabilities.length > 0 ? snap.signerCapabilities.join(", ") : dim("none")]
+        ["Signer Capabilities", snap.signerCapabilities.length > 0 ? snap.signerCapabilities.join(", ") : dim("none")],
+        ["Session Mode", snap.status === "active" ? "smart-wallet calls, preflight simulation, sponsorship eligible, managed nonce" : dim("not active")],
+        ["Local Mode", localState.evmAddress || localSolanaAddress ? "local key signing; sponsorship only where command supports it" : dim("not configured")]
       ];
       if (snap.connectionRequestId) {
         pairs.push(["Connection Request ID", snap.connectionRequestId]);
@@ -6263,6 +6298,41 @@ Examples:
 }
 
 // src/commands/agent-prompt.ts
+var AGENT_PROMPT_SCOPES = [
+  "wallet",
+  "evm",
+  "solana",
+  "webhook",
+  "app",
+  "data",
+  "xchain"
+];
+var SCOPE_COMMAND_PATHS = {
+  app: ["app", "auth", "config"],
+  data: ["evm data", "evm logs", "evm block", "evm tx", "evm receipt"],
+  evm: ["evm"],
+  solana: ["solana"],
+  wallet: [
+    "wallet",
+    "evm send",
+    "evm contract",
+    "evm swap",
+    "evm approve",
+    "evm status",
+    "xchain bridge"
+  ],
+  webhook: ["webhook", "config set webhook-api-key"],
+  xchain: ["xchain"]
+};
+var SCOPE_EXAMPLE_MATCHERS = {
+  app: [" app ", " auth ", " config "],
+  data: [" evm data ", " evm logs ", " evm block ", " evm tx ", " evm receipt "],
+  evm: [" evm "],
+  solana: [" solana "],
+  wallet: [" wallet ", " evm send ", " evm swap ", " evm approve ", " xchain bridge "],
+  webhook: [" webhook "],
+  xchain: [" xchain "]
+};
 var RETRYABLE_CODES = /* @__PURE__ */ new Set([
   ErrorCode.RATE_LIMITED,
   ErrorCode.NETWORK_ERROR
@@ -6281,6 +6351,7 @@ var ERROR_RECOVERY = {
   PAYMENT_REQUIRED: "Fund your x402 wallet or switch to API key auth",
   SETUP_REQUIRED: "Run preflight: alchemy --json --no-interactive config status, then follow nextCommands",
   QUOTE_FAILED: "Quote unavailable; check data.cause for the specific reason (INSUFFICIENT_BALANCE, INSUFFICIENT_LIQUIDITY, UNSUPPORTED_ROUTE, QUOTE_REVERTED, QUOTE_FAILED) and follow the hint",
+  PREFLIGHT_REVERT: "Transaction preflight reverted; inspect data.reason, fix balance/allowance/calldata, and retry with --dry-run when available",
   INTERNAL_ERROR: "Unexpected error; retry or report a bug"
 };
 function buildCommandSchema(cmd) {
@@ -6315,6 +6386,56 @@ function buildCommandSchema(cmd) {
   }
   return schema;
 }
+function commandMatchesPath(cmd, path) {
+  if (path[0] !== cmd.name) return null;
+  if (path.length === 1) return cmd;
+  if (!cmd.subcommands) return null;
+  const childMatches = filterCommandSchemas(cmd.subcommands, [path.slice(1)]);
+  if (childMatches.length === 0) return null;
+  return {
+    ...cmd,
+    subcommands: childMatches
+  };
+}
+function filterCommandSchemas(commands, paths) {
+  const filtered = [];
+  for (const cmd of commands) {
+    const matches = paths.map((path) => commandMatchesPath(cmd, path)).filter((match) => Boolean(match));
+    if (matches.length === 0) continue;
+    if (matches.some((match) => match === cmd)) {
+      filtered.push(cmd);
+      continue;
+    }
+    const subcommands = matches.flatMap((match) => match.subcommands ?? []);
+    filtered.push({
+      ...cmd,
+      subcommands
+    });
+  }
+  return filtered;
+}
+function parseScope(value) {
+  if (value === void 0) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (AGENT_PROMPT_SCOPES.includes(normalized)) {
+    return normalized;
+  }
+  throw errInvalidArgs(
+    `Unknown agent-prompt scope '${value}'. Use one of: ${AGENT_PROMPT_SCOPES.join(", ")}.`
+  );
+}
+function applyScope(payload, scope) {
+  if (!scope) return;
+  payload.scope = scope;
+  payload.commands = filterCommandSchemas(
+    payload.commands,
+    SCOPE_COMMAND_PATHS[scope].map((path) => path.split(" "))
+  );
+  const matchers = SCOPE_EXAMPLE_MATCHERS[scope];
+  payload.examples = payload.examples.filter(
+    (example) => matchers.some((matcher) => ` ${example} `.includes(matcher))
+  );
+}
 function buildAgentPrompt(program2) {
   const errors = {};
   for (const [code, exitCode] of Object.entries(EXIT_CODES)) {
@@ -6343,6 +6464,11 @@ function buildAgentPrompt(program2) {
       command: "alchemy --json --no-interactive config status",
       description: "Check auth readiness before first command. Use capabilities.rpc_data/admin_api/notify_webhooks/wallet_signing/x402 to scope setup to the intended command family."
     },
+    transactionPreflight: [
+      "Before `evm send`, check the sender's native balance with `alchemy --json --no-interactive evm data balance <address> -n <network>`.",
+      "Before ERC-20 sends, swaps, approvals, or bridges, verify the source token balance/allowance or request a quote first; do not infer spendability from a configured wallet alone.",
+      "If a balance is zero or below the requested amount, stop and report the funding gap instead of retrying the transaction."
+    ],
     runtimeDiscovery: {
       installed: {
         command: "alchemy --json --no-interactive agent-prompt",
@@ -6476,6 +6602,11 @@ function formatAsSystemPrompt(payload) {
   lines.push(`  Command: ${payload.preflight.command}`);
   lines.push(`  ${payload.preflight.description}`);
   lines.push("");
+  lines.push("Transaction preflight:");
+  for (const rule of payload.transactionPreflight) {
+    lines.push(`  - ${rule}`);
+  }
+  lines.push("");
   lines.push("Runtime discovery:");
   lines.push(`  Installed CLI: ${payload.runtimeDiscovery.installed.command}`);
   lines.push(`    ${payload.runtimeDiscovery.installed.description}`);
@@ -6531,13 +6662,18 @@ function formatAsSystemPrompt(payload) {
   return lines.join("\n");
 }
 function registerAgentPrompt(program2) {
-  program2.command("agent-prompt").description("Emit complete agent/automation usage instructions").option("--commands <list>", "Filter to specific commands in JSON output (requires --json). Comma-separated (e.g. data,rpc,gas)").action((opts) => {
-    const payload = buildAgentPrompt(program2);
-    if (opts.commands) {
-      const filter = new Set(opts.commands.split(",").map((s) => s.trim().toLowerCase()));
-      payload.commands = payload.commands.filter((cmd) => filter.has(cmd.name.toLowerCase()));
+  program2.command("agent-prompt").description("Emit complete agent/automation usage instructions").option("--scope <scope>", "Filter output to a command area: wallet, evm, solana, webhook, app, data, xchain").option("--commands <list>", "Filter to specific commands in JSON output (requires --json). Comma-separated (e.g. data,rpc,gas)").action((opts) => {
+    try {
+      const payload = buildAgentPrompt(program2);
+      applyScope(payload, parseScope(opts.scope));
+      if (opts.commands) {
+        const filter = new Set(opts.commands.split(",").map((s) => s.trim().toLowerCase()));
+        payload.commands = payload.commands.filter((cmd) => filter.has(cmd.name.toLowerCase()));
+      }
+      printHuman(formatAsSystemPrompt(payload), payload);
+    } catch (err) {
+      exitWithError(err);
     }
-    printHuman(formatAsSystemPrompt(payload), payload);
   });
 }
 
@@ -6670,6 +6806,55 @@ function registrySymbolSuggestions(network) {
   return listRegistryTokens(network).map((t) => t.symbol);
 }
 
+// src/lib/preflight-errors.ts
+function errorText(err) {
+  if (err instanceof CLIError) {
+    return [err.message, err.details].filter(Boolean).join(" ");
+  }
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}
+function cleanReason(value) {
+  return value.replace(/^["'`]+|["'`]+$/g, "").replace(/\s+/g, " ").trim();
+}
+function extractRevertReason(text) {
+  const patterns = [
+    /An error occurred while executing user operation:\s*["'`]?([^"'`\n]+)["'`]?/i,
+    /reverted with the following reason:\s*["'`]?([^"'`\n]+)["'`]?/i,
+    /execution reverted(?::|[ \t]+with reason string)[ \t]*["'`]?([^"'`\n]+)["'`]?/i,
+    /reverted with (?:the )?reason(?: string)?:?[ \t]*["'`]?([^"'`\n]+)["'`]?/i,
+    /\breason:[ \t]*["'`]?([^"'`\n]+)["'`]?/i,
+    /\brevert(?:ed)?[: \t]+["'`]?([^"'`\n]+)["'`]?/i
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    const reason = match?.[1] ? cleanReason(match[1]) : "";
+    if (reason) return reason;
+  }
+  if (/\b(revert|reverted|execution reverted|call exception)\b/i.test(text)) {
+    return "execution reverted";
+  }
+  return null;
+}
+function normalizePreflightRevertError(err) {
+  if (err instanceof CLIError && err.code === ErrorCode.PREFLIGHT_REVERT) {
+    return err;
+  }
+  const detail = errorText(err);
+  const reason = extractRevertReason(detail);
+  if (!reason) return null;
+  return errPreflightRevert(reason, detail || void 0);
+}
+async function withPreflightRevert(fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    throw normalizePreflightRevertError(err) ?? err;
+  }
+}
+
 // src/commands/approve.ts
 function isNativeToken(address3) {
   return address3.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase();
@@ -6848,10 +7033,10 @@ async function performApprove(program2, spenderArg, opts) {
   const { id } = await withSpinner(
     "Sending approval\u2026",
     "Approval submitted",
-    () => client.sendCalls({
+    () => withPreflightRevert(() => client.sendCalls({
       calls,
       capabilities: paymaster ? { paymaster } : void 0
-    })
+    }))
   );
   const status = await withSpinner(
     "Waiting for confirmation\u2026",
@@ -7296,10 +7481,10 @@ async function performContractCall(program2, addressArg, functionArg, opts) {
   const { id } = await withSpinner(
     "Sending transaction\u2026",
     "Transaction submitted",
-    () => client.sendCalls({
+    () => withPreflightRevert(() => client.sendCalls({
       calls: [call],
       capabilities: paymaster ? { paymaster } : void 0
-    })
+    }))
   );
   const status = await withSpinner(
     "Waiting for confirmation\u2026",
@@ -8473,7 +8658,7 @@ Examples:
         dryRun: opts.dryRun
       });
     } catch (err) {
-      const { exitWithError: exitWithError2 } = await import("./errors-6BEPCY5N.js");
+      const { exitWithError: exitWithError2 } = await import("./errors-VS7SGW7B.js");
       exitWithError2(err);
     }
   });
@@ -8550,10 +8735,10 @@ async function performEvmSend(program2, toArg, amountArg, tokenAddress, opts = {
   const { id } = await withSpinner(
     "Sending transaction\u2026",
     "Transaction submitted",
-    () => client.sendCalls({
+    () => withPreflightRevert(() => client.sendCalls({
       calls,
       capabilities: paymaster ? { paymaster } : void 0
-    })
+    }))
   );
   const status = await withSpinner(
     "Waiting for confirmation\u2026",
@@ -8679,7 +8864,7 @@ function buildWalletQuoteClient(program2, address3) {
 }
 
 // src/lib/quote-errors.ts
-function errorText(err) {
+function errorText2(err) {
   if (err instanceof CLIError) {
     return [err.message, err.details].filter(Boolean).join(" ");
   }
@@ -8737,7 +8922,7 @@ function normalizeQuoteError(err, flow) {
   if (err instanceof CLIError && err.code !== ErrorCode.RPC_ERROR && err.code !== ErrorCode.INTERNAL_ERROR) {
     return err;
   }
-  const detail = errorText(err);
+  const detail = errorText2(err);
   const cause = classifyQuoteFailure(detail);
   return new CLIError(
     ErrorCode.QUOTE_FAILED,
@@ -8810,10 +8995,10 @@ async function prepareQuoteForExecution(client, quote) {
   const preparedQuote = await withSpinner(
     "Preparing swap\u2026",
     "Swap prepared",
-    () => client.prepareCalls({
+    () => withPreflightRevert(() => client.prepareCalls({
       ...permitQuote.modifiedRequest,
       paymasterPermitSignature: permitSignature
-    })
+    }))
   );
   if ("type" in preparedQuote && preparedQuote.type === "paymaster-permit") {
     throw errInvalidArgs("Swap quote still requires a paymaster permit after signing. The quote response format may be unsupported.");
@@ -8954,14 +9139,14 @@ async function performSwapExecute(program2, opts) {
     async () => {
       if ("rawCalls" in preparedQuote && preparedQuote.rawCalls === true) {
         const rawCallsQuote = preparedQuote;
-        return client.sendCalls({
+        return withPreflightRevert(() => client.sendCalls({
           calls: rawCallsQuote.calls,
           capabilities: paymaster ? { paymaster } : void 0
-        });
+        }));
       }
       const executablePreparedQuote = preparedQuote;
       const signedQuote = await client.signPreparedCalls(executablePreparedQuote);
-      return client.sendPreparedCalls(signedQuote);
+      return withPreflightRevert(() => client.sendPreparedCalls(signedQuote));
     }
   );
   const status = await withSpinner(
@@ -9516,10 +9701,10 @@ async function prepareQuoteForExecution2(client, quote) {
   const preparedQuote = await withSpinner(
     "Preparing bridge\u2026",
     "Bridge prepared",
-    () => client.prepareCalls({
+    () => withPreflightRevert(() => client.prepareCalls({
       ...permitQuote.modifiedRequest,
       paymasterPermitSignature: permitSignature
-    })
+    }))
   );
   if ("type" in preparedQuote && preparedQuote.type === "paymaster-permit") {
     throw errInvalidArgs("Bridge quote still requires a paymaster permit after signing. The quote response format may be unsupported.");
@@ -9673,14 +9858,14 @@ async function performBridgeExecute(program2, opts) {
     async () => {
       if ("rawCalls" in preparedQuote && preparedQuote.rawCalls === true) {
         const rawCallsQuote = preparedQuote;
-        return client.sendCalls({
+        return withPreflightRevert(() => client.sendCalls({
           calls: rawCallsQuote.calls,
           capabilities: paymaster ? { paymaster } : void 0
-        });
+        }));
       }
       const executablePreparedQuote = preparedQuote;
       const signedQuote = await client.signPreparedCalls(executablePreparedQuote);
-      return client.sendPreparedCalls(signedQuote);
+      return withPreflightRevert(() => client.sendPreparedCalls(signedQuote));
     }
   );
   const status = await withSpinner(
@@ -10396,7 +10581,7 @@ async function flushProcessOutput() {
 }
 program.name("alchemy").description(
   "The Alchemy CLI lets you query blockchain data, call JSON-RPC methods, and manage your Alchemy configuration."
-).version("0.13.0", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option(
+).version("0.14.0", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option(
   "-n, --network <network>",
   "Target network for networked commands"
 ).option("--x402", "Use x402 wallet-based gateway auth").option(
@@ -10583,11 +10768,11 @@ ${styledLine}`;
     "wallet"
   ];
   if (!skipAppPrompt.includes(cmdName) && isInteractiveAllowed(program) && !opts.apiKey && !process.env.ALCHEMY_API_KEY) {
-    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-GELBKDTP.js");
+    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-IRTGQL4A.js");
     const authToken = resolveAuthToken2(cfg);
     const hasApiKey = Boolean(cfg.api_key?.trim() || cfg.app?.apiKey);
     if (authToken && !hasApiKey) {
-      const { selectAppAfterAuth } = await import("./auth-YB6AALZO.js");
+      const { selectAppAfterAuth } = await import("./auth-ZBEPAFEP.js");
       console.log("");
       console.log(`  No app selected. Please select an app to continue.`);
       await selectAppAfterAuth(authToken);
@@ -10622,7 +10807,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-TYRUMFUL.js");
+      const { runOnboarding } = await import("./onboarding-QE43IUEK.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -10636,7 +10821,7 @@ ${styledLine}`;
         latestForInteractiveStartup
       );
     }
-    const { startREPL } = await import("./interactive-6SOB4IYV.js");
+    const { startREPL } = await import("./interactive-XNDXNMAJ.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {

package/dist/{interactive-6SOB4IYV.js → interactive-XNDXNMAJ.js}

@@ -2,14 +2,14 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getSetupMethod
-} from "./chunk-DWNXGFON.js";
-import "./chunk-RPSHRYCZ.js";
+} from "./chunk-RQDWIB62.js";
+import "./chunk-EJB4WDTU.js";
 import {
   getRPCNetworkIds
-} from "./chunk-PRSZJXA6.js";
+} from "./chunk-CXR7CCJ7.js";
 import {
   getUpdateNoticeLines
-} from "./chunk-OE6B6S2H.js";
+} from "./chunk-22KBYYLI.js";
 import {
   bold,
   brand,
@@ -17,18 +17,18 @@ import {
   dim,
   green,
   setBrandedHelpSuppressed
-} from "./chunk-DXQAGBW6.js";
+} from "./chunk-OIRERSZT.js";
 import {
   configDir,
   load
-} from "./chunk-LANOFNO6.js";
+} from "./chunk-PISUI34T.js";
 import {
   bgRgb,
   isJSONMode,
   noColor,
   rgb,
   setReplMode
-} from "./chunk-5BEJA752.js";
+} from "./chunk-CFIDLPKB.js";
 
 // src/commands/interactive.ts
 import * as readline from "readline";

package/dist/{onboarding-TYRUMFUL.js → onboarding-QE43IUEK.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getUpdateNoticeLines
-} from "./chunk-OE6B6S2H.js";
+} from "./chunk-22KBYYLI.js";
 import {
   bold,
   brand,
@@ -10,12 +10,12 @@ import {
   dim,
   green,
   promptText
-} from "./chunk-DXQAGBW6.js";
+} from "./chunk-OIRERSZT.js";
 import {
   load,
   save
-} from "./chunk-LANOFNO6.js";
-import "./chunk-5BEJA752.js";
+} from "./chunk-PISUI34T.js";
+import "./chunk-CFIDLPKB.js";
 
 // src/commands/onboarding.ts
 async function runOnboarding(_program, latestUpdate = null) {
@@ -38,7 +38,7 @@ async function runOnboarding(_program, latestUpdate = null) {
   if (answer === null) {
     return false;
   }
-  const { performBrowserLogin, AUTH_PORT, getLoginUrl } = await import("./auth-5XFZB2BU.js");
+  const { performBrowserLogin, AUTH_PORT, getLoginUrl } = await import("./auth-57YPPTNF.js");
   console.log(`  Opening browser to log in...`);
   console.log(`  ${dim(getLoginUrl(AUTH_PORT))}`);
   console.log(`  ${dim("Waiting for authentication...")}`);
@@ -51,7 +51,7 @@ async function runOnboarding(_program, latestUpdate = null) {
       auth_token_expires_at: result.expiresAt
     });
     console.log(`  ${green("\u2713")} Logged in successfully`);
-    const { selectAppAfterAuth } = await import("./auth-YB6AALZO.js");
+    const { selectAppAfterAuth } = await import("./auth-ZBEPAFEP.js");
     await selectAppAfterAuth(result.token);
     return true;
   } catch (err) {

package/dist/{policy-prompt-LY6DMMT4.js → policy-prompt-UNNIF63S.js}

@@ -5,11 +5,11 @@ import {
   errNotLoggedInForPolicyLookup,
   errSponsorshipNeedsPolicy,
   selectOrCreatePolicy
-} from "./chunk-PYIVNQEI.js";
-import "./chunk-PRSZJXA6.js";
-import "./chunk-DXQAGBW6.js";
-import "./chunk-LANOFNO6.js";
-import "./chunk-5BEJA752.js";
+} from "./chunk-M7HFRKW6.js";
+import "./chunk-CXR7CCJ7.js";
+import "./chunk-OIRERSZT.js";
+import "./chunk-PISUI34T.js";
+import "./chunk-CFIDLPKB.js";
 export {
   createPolicyInteractive,
   errNotLoggedInForPolicyLookup,

package/dist/{resolve-GELBKDTP.js → resolve-IRTGQL4A.js}

@@ -26,9 +26,9 @@ import {
   resolveWalletSession,
   resolveX402,
   resolveX402Client
-} from "./chunk-PRSZJXA6.js";
-import "./chunk-LANOFNO6.js";
-import "./chunk-5BEJA752.js";
+} from "./chunk-CXR7CCJ7.js";
+import "./chunk-PISUI34T.js";
+import "./chunk-CFIDLPKB.js";
 export {
   adminClientFromFlags,
   apiKeyClientFromFlags,

package/package.json

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

package/dist/auth-YB6AALZO.js

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
-import {
-  registerAuth,
-  selectAppAfterAuth
-} from "./chunk-5DR7BHUX.js";
-import "./chunk-I6YQX7PF.js";
-import "./chunk-RPSHRYCZ.js";
-import "./chunk-PRSZJXA6.js";
-import "./chunk-DXQAGBW6.js";
-import "./chunk-LANOFNO6.js";
-import "./chunk-5BEJA752.js";
-export {
-  registerAuth,
-  selectAppAfterAuth
-};