@alchemy/cli 0.2.0 → 0.2.1

package/README.md

@@ -57,6 +57,9 @@ alchemy
 
 # Agent/script-friendly command
 alchemy balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --json --no-interactive
+
+# Agent checks whether a newer CLI version is available
+alchemy update-check --json --no-interactive
 ```
 
 #### Agent bootstrap
@@ -70,6 +73,8 @@ alchemy --json agent-prompt
 
 This returns a single JSON document with execution policy, preflight instructions, auth matrix, the full command tree with all arguments and options, error codes with recovery actions, and example invocations. No external docs required.
 
+Agents can also call `alchemy --json --no-interactive update-check` to retrieve the current CLI version, latest known version, and install command for upgrades.
+
 ## Command Reference
 
 Run commands as `alchemy <command>`.
@@ -151,6 +156,7 @@ Use `alchemy help` or `alchemy help <command>` for generated command help.
 | `apps origin-allowlist <id>` | Updates app origin allowlist | `alchemy apps origin-allowlist <app-id> --origins https://example.com` |
 | `apps ip-allowlist <id>` | Updates app IP allowlist | `alchemy apps ip-allowlist <app-id> --ips 1.2.3.4,5.6.7.8` |
 | `setup status` | Shows setup status + next commands | `alchemy setup status` |
+| `update-check` | Checks whether a newer CLI version is available | `alchemy update-check --json --no-interactive` |
 | `config set ...` | Sets config values | `alchemy config set api-key <key>` |
 | `config get <key>` | Gets one config value | `alchemy config get network` |
 | `config list` | Lists all config values | `alchemy config list` |
@@ -180,7 +186,7 @@ These apply to all commands.
 |---|---|---|
 | `--json` | — | Force JSON output |
 | `-q, --quiet` | — | Suppress non-essential output |
-| `-v, --verbose` | — | Enable verbose output |
+| `--verbose` | — | Enable verbose output |
 | `--no-color` | `NO_COLOR` | Disable color output |
 | `--reveal` | — | Show secrets in plain text (TTY only) |
 
@@ -317,6 +323,7 @@ Use `--no-interactive` to disable REPL/prompts in automation.
 
 - TTY: formatted human output
 - Non-TTY: JSON output (script-friendly)
+- `-v`, `--version`: prints the CLI version
 - `--json`: forces JSON output in any context
 - `--verbose` or `alchemy config set verbose true`: includes richer payload output on supported commands
 

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

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isInteractiveAllowed
-} from "./chunk-VRBWUQHA.js";
+} from "./chunk-SDUCDSCZ.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/{chunk-VRBWUQHA.js → chunk-SDUCDSCZ.js}

@@ -1047,6 +1047,109 @@ function isInteractiveAllowed(program) {
   return true;
 }
 
+// src/lib/update-check.ts
+import { execFileSync } from "child_process";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var UPDATE_INSTALL_COMMAND = "npm i -g @alchemy/cli";
+function cachePath() {
+  return configPath().replace(/config\.json$/, ".update-check");
+}
+function readCache() {
+  try {
+    return JSON.parse(readFileSync2(cachePath(), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeCache(cache) {
+  try {
+    const p = cachePath();
+    mkdirSync2(dirname2(p), { recursive: true });
+    writeFileSync2(p, JSON.stringify(cache), { mode: 384 });
+  } catch {
+  }
+}
+function fetchLatestVersion() {
+  try {
+    const result = execFileSync("npm", ["view", "@alchemy/cli", "version"], {
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return result.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function semverLT(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return true;
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return false;
+  }
+  return false;
+}
+function currentVersion() {
+  return true ? "0.2.1" : "0.0.0";
+}
+function toUpdateStatus(latestVersion, checkedAt) {
+  const current = currentVersion();
+  return {
+    currentVersion: current,
+    latestVersion,
+    updateAvailable: latestVersion ? semverLT(current, latestVersion) : false,
+    installCommand: UPDATE_INSTALL_COMMAND,
+    checkedAt
+  };
+}
+function getUpdateStatus() {
+  const cache = readCache();
+  if (cache && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+    return toUpdateStatus(cache.latest, cache.checkedAt);
+  }
+  const latest = fetchLatestVersion();
+  if (latest) {
+    const checkedAt = Date.now();
+    writeCache({ latest, checkedAt });
+    return toUpdateStatus(latest, checkedAt);
+  }
+  if (cache) {
+    return toUpdateStatus(cache.latest, cache.checkedAt);
+  }
+  return toUpdateStatus(null, null);
+}
+function getAvailableUpdate() {
+  const current = currentVersion();
+  const cache = readCache();
+  if (cache && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+    return semverLT(current, cache.latest) ? cache.latest : null;
+  }
+  const latest = fetchLatestVersion();
+  if (latest) {
+    writeCache({ latest, checkedAt: Date.now() });
+    return semverLT(current, latest) ? latest : null;
+  }
+  return null;
+}
+function getUpdateNoticeLines(latest) {
+  const yellow2 = esc("33");
+  const bold2 = esc("1");
+  const dim2 = esc("2");
+  return [
+    `  ${yellow2("Update available")} ${dim2(currentVersion())} \u2192 ${bold2(latest)}`,
+    `  Run ${bold2(UPDATE_INSTALL_COMMAND)} to update`
+  ];
+}
+function printUpdateNotice(latest) {
+  process.stderr.write(`
+${getUpdateNoticeLines(latest).join("\n")}
+
+`);
+}
+
 export {
   noColor,
   identity,
@@ -1110,5 +1213,9 @@ export {
   timeAgo,
   etherscanTxURL,
   brandedHelp,
-  isInteractiveAllowed
+  isInteractiveAllowed,
+  getUpdateStatus,
+  getAvailableUpdate,
+  getUpdateNoticeLines,
+  printUpdateNotice
 };

package/dist/{chunk-VD5WQHLQ.js → chunk-XP5KF4W2.js}

@@ -40,7 +40,7 @@ import {
   toMap,
   withSpinner,
   yellow
-} from "./chunk-VRBWUQHA.js";
+} from "./chunk-SDUCDSCZ.js";
 
 // src/lib/client-utils.ts
 function isLocalhost(hostname) {

package/dist/index.js

@@ -14,13 +14,13 @@ import {
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-VD5WQHLQ.js";
+} from "./chunk-XP5KF4W2.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-MAKSV2EA.js";
+} from "./chunk-HBRTTBCY.js";
 import {
   EXIT_CODES,
   ErrorCode,
@@ -42,6 +42,8 @@ import {
   exitWithError,
   failBadge,
   formatCommanderError,
+  getAvailableUpdate,
+  getUpdateStatus,
   green,
   identity,
   isInteractiveAllowed,
@@ -54,6 +56,7 @@ import {
   printKeyValueBox,
   printSyntaxJSON,
   printTable,
+  printUpdateNotice,
   promptSelect,
   quiet,
   setFlags,
@@ -62,7 +65,7 @@ import {
   verbose,
   weiToEth,
   withSpinner
-} from "./chunk-VRBWUQHA.js";
+} from "./chunk-SDUCDSCZ.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -1678,7 +1681,8 @@ function buildAgentPrompt(program2) {
       "Always pass --json --no-interactive",
       "Parse stdout as JSON on exit code 0",
       "Parse stderr as JSON on nonzero exit code",
-      "Never run bare 'alchemy' without --json --no-interactive"
+      "Never run bare 'alchemy' without --json --no-interactive",
+      "Run alchemy --json --no-interactive update-check when you need to detect available CLI upgrades"
     ],
     preflight: {
       command: "alchemy --json setup status",
@@ -1742,6 +1746,7 @@ function buildAgentPrompt(program2) {
     errors,
     examples: [
       "alchemy --json --no-interactive setup status",
+      "alchemy --json --no-interactive update-check",
       "alchemy --json --no-interactive balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --api-key $ALCHEMY_API_KEY",
       "alchemy --json --no-interactive apps list --access-key $ALCHEMY_ACCESS_KEY",
       "alchemy --json --no-interactive rpc eth_blockNumber --api-key $ALCHEMY_API_KEY",
@@ -1800,6 +1805,27 @@ function registerAgentPrompt(program2) {
   });
 }
 
+// src/commands/update-check.ts
+function formatCheckedAt(checkedAt) {
+  return checkedAt ? new Date(checkedAt).toISOString() : dim("(unknown)");
+}
+function registerUpdateCheck(program2) {
+  program2.command("update-check").description("Check whether a newer CLI version is available").action(() => {
+    const status = getUpdateStatus();
+    if (isJSONMode()) {
+      printJSON(status);
+      return;
+    }
+    printKeyValueBox([
+      ["Current version", status.currentVersion],
+      ["Latest version", status.latestVersion ?? dim("(unknown)")],
+      ["Update available", status.updateAvailable ? "yes" : "no"],
+      ["Checked at", formatCheckedAt(status.checkedAt)],
+      ["Install", status.installCommand]
+    ]);
+  });
+}
+
 // src/index.ts
 var hBrand = noColor ? identity : (s) => `\x1B[38;2;54;63;249m${s}\x1B[39m`;
 var hBold = esc("1");
@@ -1837,7 +1863,7 @@ var ROOT_COMMAND_PILLARS = [
   },
   {
     label: "Admin",
-    commands: ["apps", "config", "setup", "agent-prompt", "version", "help"]
+    commands: ["apps", "config", "setup", "agent-prompt", "update-check", "version", "help"]
   }
 ];
 function formatCommandSignature(sub) {
@@ -1872,12 +1898,29 @@ var findCommandByPath = (root, path) => {
   }
   return current;
 };
+var cachedAvailableUpdate;
+var updateShownDuringInteractiveStartup = false;
+function getAvailableUpdateOnce() {
+  if (cachedAvailableUpdate === void 0) {
+    cachedAvailableUpdate = getAvailableUpdate();
+  }
+  return cachedAvailableUpdate;
+}
+function resetUpdateNoticeState() {
+  cachedAvailableUpdate = void 0;
+  updateShownDuringInteractiveStartup = false;
+}
 program.name("alchemy").description(
   "The Alchemy CLI lets you query blockchain data, call JSON-RPC methods, and manage your Alchemy configuration."
-).version("0.2.0").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.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(
   "-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({
+).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) => {
+  if (err.code === "commander.help" || err.code === "commander.helpDisplayed" || err.code === "commander.version") {
+    process.exit(0);
+  }
+  process.exit(EXIT_CODES.INVALID_ARGS);
+}).configureOutput({
   outputError(str, write) {
     write(formatCommanderError(str));
   }
@@ -2018,27 +2061,39 @@ ${styledLine}`;
 }).hook("postAction", () => {
   if (!isJSONMode() && !quiet) {
     console.log("");
+    if (!updateShownDuringInteractiveStartup) {
+      const latest = getAvailableUpdateOnce();
+      if (latest) printUpdateNotice(latest);
+    }
   }
+  resetUpdateNoticeState();
 }).action(async () => {
   const cfg = load();
   if (!isSetupComplete(cfg) && !isInteractiveAllowed(program)) {
     throw errSetupRequired(getSetupStatus(cfg));
   }
   if (isInteractiveAllowed(program)) {
+    let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-IKIXUTY7.js");
-      const completed = await runOnboarding(program);
+      const { runOnboarding } = await import("./onboarding-YA32OJOT.js");
+      const latest = getAvailableUpdateOnce();
+      const completed = await runOnboarding(program, latest);
+      updateShownDuringInteractiveStartup = Boolean(latest);
+      latestForInteractiveStartup = null;
       if (!completed) {
         return;
       }
+    } else {
+      latestForInteractiveStartup = getAvailableUpdateOnce();
+      updateShownDuringInteractiveStartup = Boolean(latestForInteractiveStartup);
     }
-    const { startREPL } = await import("./interactive-CP6E23OD.js");
+    const { startREPL } = await import("./interactive-L7N4HI7K.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {
       }
     });
-    await startREPL(program);
+    await startREPL(program, latestForInteractiveStartup);
     return;
   }
   program.help();
@@ -2066,6 +2121,7 @@ registerSetup(program);
 registerConfig(program);
 registerSolana(program);
 registerAgentPrompt(program);
+registerUpdateCheck(program);
 registerVersion(program);
 program.command("help [command...]").description("display help for command").action((commandPath) => {
   if (!commandPath || commandPath.length === 0) {

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

@@ -3,7 +3,7 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getRPCNetworkIds,
   getSetupMethod
-} from "./chunk-MAKSV2EA.js";
+} from "./chunk-HBRTTBCY.js";
 import {
   bgRgb,
   bold,
@@ -11,6 +11,7 @@ import {
   brandedHelp,
   configDir,
   dim,
+  getUpdateNoticeLines,
   green,
   isJSONMode,
   load,
@@ -18,7 +19,7 @@ import {
   rgb,
   setBrandedHelpSuppressed,
   setReplMode
-} from "./chunk-VRBWUQHA.js";
+} from "./chunk-SDUCDSCZ.js";
 
 // src/commands/interactive.ts
 import * as readline from "readline";
@@ -88,6 +89,7 @@ var COMMAND_NAMES = [
   "config get",
   "config list",
   "help",
+  "update-check",
   "network",
   "network list",
   "nfts",
@@ -136,7 +138,7 @@ function saveReplHistory(lines) {
   mkdirSync(dirname(historyFilePath), { recursive: true, mode: 493 });
   writeFileSync(historyFilePath, normalized.join("\n") + "\n", { mode: 384 });
 }
-async function startREPL(program) {
+async function startREPL(program, latestUpdate = null) {
   if (!stdin.isTTY) return;
   setReplMode(true);
   setBrandedHelpSuppressed(true);
@@ -217,6 +219,12 @@ async function startREPL(program) {
     console.log(`  ${green("\u2713")} ${dim(`Configured auth: ${formatSetupMethodLabel()}`)}`);
     console.log(`  ${dim("Run commands directly (no 'alchemy' prefix).")}`);
     console.log("");
+    if (latestUpdate) {
+      for (const line of getUpdateNoticeLines(latestUpdate)) {
+        console.log(line);
+      }
+      console.log("");
+    }
     console.log(`  ${brand("\u25C6")} ${bold("Quick commands")}`);
     console.log(`  ${dim("- rpc eth_chainId")}`);
     console.log(`  ${dim("- config list")}`);

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

@@ -5,12 +5,13 @@ import {
   generateAndPersistWallet,
   importAndPersistWallet,
   selectOrCreateApp
-} from "./chunk-VD5WQHLQ.js";
+} from "./chunk-XP5KF4W2.js";
 import {
   bold,
   brand,
   brandedHelp,
   dim,
+  getUpdateNoticeLines,
   green,
   load,
   maskIf,
@@ -18,7 +19,7 @@ import {
   promptSelect,
   promptText,
   save
-} from "./chunk-VRBWUQHA.js";
+} from "./chunk-SDUCDSCZ.js";
 
 // src/commands/onboarding.ts
 function printNextSteps(method) {
@@ -106,7 +107,7 @@ async function runX402Onboarding() {
   save({ ...cfg, x402: true });
   console.log(`  ${green("\u2713")} x402 enabled with wallet ${wallet.address}`);
 }
-async function runOnboarding(_program) {
+async function runOnboarding(_program, latestUpdate = null) {
   process.stdout.write(brandedHelp({ force: true }));
   console.log("");
   console.log(`  ${brand("\u25C6")} ${bold("Welcome to Alchemy CLI")}`);
@@ -115,6 +116,12 @@ async function runOnboarding(_program) {
   console.log(`  ${dim("  Choose one auth path to continue.")}`);
   console.log(`  ${dim("  Tip: select 'exit' to skip setup for now.")}`);
   console.log("");
+  if (latestUpdate) {
+    for (const line of getUpdateNoticeLines(latestUpdate)) {
+      console.log(line);
+    }
+    console.log("");
+  }
   const method = await promptSelect({
     message: "Choose an auth setup path",
     options: [

package/package.json

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