@alchemy/cli 0.1.5 → 0.2.1

package/README.md

@@ -18,6 +18,63 @@ Or run without installing globally:
 npx @alchemy/cli <command>
 ```
 
+## Getting Started
+
+### Authentication Quick Start
+
+Authentication is required before making requests. Configure auth first, then run commands.
+
+If you are using the CLI as a human in an interactive terminal, the easiest path is:
+
+```bash
+alchemy
+```
+
+Then follow the setup flow in the terminal UI to configure auth.
+
+Know which auth method does what:
+
+- **API key** - direct auth for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`)
+- **Access key** - Admin/API app management; app setup/selection can also provide API key auth for blockchain queries
+- **x402 wallet auth** - wallet-authenticated, pay-per-request model for supported blockchain queries
+
+If you use Notify webhooks, add webhook auth on top via `alchemy config set webhook-api-key <key>`, `--webhook-api-key`, or `ALCHEMY_WEBHOOK_API_KEY`.
+
+For setup commands, env vars, and resolution order, see [Authentication Reference](#authentication-reference).
+
+### Usage By Workflow
+
+After auth is configured, use the CLI differently depending on who is driving it:
+
+- **Humans (interactive terminal):** start with `alchemy` and use the terminal UI/setup flow; this is the recommended path for human usage
+- **Agents/scripts (automation):** always use `--json` and prefer non-interactive execution (`--no-interactive`)
+
+Quick usage examples:
+
+```bash
+# Human recommended entrypoint
+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
+
+Have your agent run `agent-prompt` as its first step to get a complete, machine-readable contract describing every command, auth method, error code, and execution rule:
+
+```bash
+# Agent runs this once to learn everything the CLI can do
+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>`.
@@ -99,10 +156,12 @@ 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` |
 | `config reset [key]` | Resets one or all config values | `alchemy config reset --yes` |
+| `agent-prompt` | Emits complete agent/automation usage instructions | `alchemy --json agent-prompt` |
 | `version` | Prints CLI version | `alchemy version` |
 
 ## Flags
@@ -127,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) |
 
@@ -176,13 +235,13 @@ Additional env vars:
 | `network list` | `--configured`, `--app-id <id>` |
 | `config reset` | `-y, --yes` |
 
-## Authentication
+## Authentication Reference
 
 The CLI supports three auth inputs:
 
 - API key for blockchain queries (`balance`, `tx`, `block`, `nfts`, `tokens`, `rpc`)
-- Access key for Admin API operations (`apps`, `chains`, configured network lookups)
-- x402 wallet key for wallet-authenticated blockchain queries
+- Access key for Admin API operations (`apps`, `chains`, configured network lookups`) and app setup/selection, which can also supply the API key used by blockchain query commands
+- x402 wallet key for wallet-authenticated blockchain queries in a pay-per-request model
 
 Notify/webhook commands use a webhook API key with resolution order:
 `--webhook-api-key` -> `ALCHEMY_WEBHOOK_API_KEY` -> `ALCHEMY_NOTIFY_AUTH_TOKEN` -> config `webhook-api-key` -> configured app webhook key.
@@ -221,6 +280,9 @@ Resolution order: `--access-key` -> `ALCHEMY_ACCESS_KEY` -> config file.
 
 #### x402 wallet auth
 
+x402 is a wallet-authenticated, pay-per-request usage model for supported blockchain queries.
+The CLI can generate or import the wallet key used for these requests.
+
 ```bash
 # Generate/import a wallet managed by CLI
 alchemy wallet generate
@@ -261,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
 
@@ -277,116 +340,3 @@ Errors are structured JSON in JSON mode:
   }
 }
 ```
-
-## Development
-
-Prerequisites:
-
-- [Node.js 22+](https://nodejs.org/)
-- [pnpm](https://pnpm.io/)
-
-### Local development setup
-
-```bash
-git clone https://github.com/alchemyplatform/alchemy-cli.git
-cd alchemy-cli
-pnpm install
-pnpm build
-pnpm link --global
-```
-
-This makes the local `alchemy` build available globally for testing.
-To unlink later: `pnpm unlink --global`.
-
-Run during development:
-
-```bash
-# Run without building
-npx tsx src/index.ts balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
-
-# Build in watch mode
-pnpm dev
-```
-
-Build:
-
-```bash
-pnpm build
-```
-
-Test:
-
-```bash
-pnpm test
-pnpm test:e2e
-```
-
-Type check:
-
-```bash
-pnpm lint
-```
-
-Coverage:
-
-```bash
-pnpm test:coverage
-```
-
-### Changesets & Releasing
-
-This project uses [Changesets](https://github.com/changesets/changesets) for versioning and release notes.
-
-**When to add a changeset:** Any PR with user-facing changes (new commands, bug fixes, flag changes, output format changes) needs a changeset. Internal changes (CI, refactors with no behavior change, docs) can skip by adding the `no-changeset` label.
-
-**How to add a changeset:**
-
-```bash
-pnpm changeset
-```
-
-You'll be prompted to pick the bump type:
-- **patch** — bug fixes, small tweaks (e.g. fixing `--json` output for a command)
-- **minor** — new commands, new flags, new capabilities
-- **major** — breaking changes (removed commands, changed flag behavior, output format changes)
-
-This creates a file like `.changeset/cool-dogs-fly.md`:
-
-```markdown
----
-"@alchemy/cli": minor
----
-
-Add `alchemy portfolio transactions` command for portfolio transaction history.
-```
-
-Write a 1-2 sentence summary of the change from a user's perspective. Commit this file with your PR.
-
-**How releases work:** When PRs with changesets merge to `main`, the publish workflow automatically:
-1. Verifies the build (typecheck, build, test)
-2. Applies version bumps and updates `CHANGELOG.md` via `changeset version`
-3. Creates a signed release commit via the GitHub Git Database API (using a GitHub App token)
-4. Publishes to npm using OIDC trusted publishing (no long-lived npm token)
-5. Creates a GitHub release/tag with notes extracted from `CHANGELOG.md`
-
-If no changesets are pending, the workflow exits cleanly — no release is created.
-
-**Release infrastructure:**
-- Repository write operations use a GitHub App (`APP_ID` variable + `APP_PRIVATE_KEY` secret)
-- npm publish uses [trusted publishing](https://docs.npmjs.com/generating-provenance-statements) (OIDC) — no `NPM_TOKEN` secret required
-- Required GitHub repo settings: `APP_ID` (variable), `APP_PRIVATE_KEY` (secret)
-- Required npm-side: configure trusted publishing for this repo/workflow at npmjs.com package settings
-
-### Endpoint Override Env Vars (Local Testing Only)
-
-These are for local/mock testing, not normal production usage:
-
-- `ALCHEMY_RPC_BASE_URL`
-- `ALCHEMY_ADMIN_API_BASE_URL`
-- `ALCHEMY_X402_BASE_URL`
-
-Safety constraints:
-
-- Only localhost targets are accepted (`localhost`, `127.0.0.1`, `::1`)
-- Non-HTTPS transport is allowed only for localhost
-- Production defaults are unchanged when unset

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

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   isInteractiveAllowed
-} from "./chunk-QKXQW4OF.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-QKXQW4OF.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,
@@ -1063,6 +1166,7 @@ export {
   debug,
   formatCommanderError,
   ErrorCode,
+  EXIT_CODES,
   CLIError,
   errAuthRequired,
   errAccessKeyRequired,
@@ -1109,5 +1213,9 @@ export {
   timeAgo,
   etherscanTxURL,
   brandedHelp,
-  isInteractiveAllowed
+  isInteractiveAllowed,
+  getUpdateStatus,
+  getAvailableUpdate,
+  getUpdateNoticeLines,
+  printUpdateNotice
 };

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

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

package/dist/index.js

@@ -14,14 +14,16 @@ import {
   splitCommaList,
   validateAddress,
   validateTxHash
-} from "./chunk-PH4BPYSY.js";
+} from "./chunk-XP5KF4W2.js";
 import {
   getRPCNetworks,
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-F7KTEZFZ.js";
+} from "./chunk-HBRTTBCY.js";
 import {
+  EXIT_CODES,
+  ErrorCode,
   bold,
   brand,
   brandedHelp,
@@ -40,6 +42,8 @@ import {
   exitWithError,
   failBadge,
   formatCommanderError,
+  getAvailableUpdate,
+  getUpdateStatus,
   green,
   identity,
   isInteractiveAllowed,
@@ -52,6 +56,7 @@ import {
   printKeyValueBox,
   printSyntaxJSON,
   printTable,
+  printUpdateNotice,
   promptSelect,
   quiet,
   setFlags,
@@ -60,7 +65,7 @@ import {
   verbose,
   weiToEth,
   withSpinner
-} from "./chunk-QKXQW4OF.js";
+} from "./chunk-SDUCDSCZ.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -1609,6 +1614,218 @@ function registerSolana(program2) {
   });
 }
 
+// src/commands/agent-prompt.ts
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  ErrorCode.RATE_LIMITED,
+  ErrorCode.NETWORK_ERROR
+]);
+var ERROR_RECOVERY = {
+  AUTH_REQUIRED: "Set ALCHEMY_API_KEY env var or run: alchemy config set api-key <key>",
+  INVALID_API_KEY: "Check your API key and set a valid one: alchemy config set api-key <key>",
+  NETWORK_NOT_ENABLED: "Enable the target network for your app at dashboard.alchemy.com",
+  INVALID_ACCESS_KEY: "Check your access key: https://dashboard.alchemy.com/",
+  ACCESS_KEY_REQUIRED: "Set ALCHEMY_ACCESS_KEY env var or run: alchemy config set access-key <key>",
+  APP_REQUIRED: "Select an app: alchemy config set app <app-id>",
+  ADMIN_API_ERROR: "Check the error message for details; verify access key permissions",
+  NETWORK_ERROR: "Check internet connection and retry",
+  RPC_ERROR: "Check RPC method, params, and network; verify API key has access",
+  INVALID_ARGS: "Check command usage via: alchemy --json help <command>",
+  NOT_FOUND: "Verify the resource identifier (address, hash, id) is correct",
+  RATE_LIMITED: "Wait and retry; consider upgrading your Alchemy plan",
+  PAYMENT_REQUIRED: "Fund your x402 wallet or switch to API key auth",
+  SETUP_REQUIRED: "Run preflight: alchemy --json setup status, then follow nextCommands",
+  INTERNAL_ERROR: "Unexpected error; retry or report a bug"
+};
+function buildCommandSchema(cmd) {
+  const schema = {
+    name: cmd.name(),
+    description: cmd.description()
+  };
+  const aliases = cmd.aliases();
+  if (aliases.length > 0) {
+    schema.aliases = aliases;
+  }
+  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(buildCommandSchema);
+  }
+  return schema;
+}
+function buildAgentPrompt(program2) {
+  const errors = {};
+  for (const [code, exitCode] of Object.entries(EXIT_CODES)) {
+    errors[code] = {
+      exitCode,
+      retryable: RETRYABLE_CODES.has(code),
+      recovery: ERROR_RECOVERY[code] ?? "Check error message"
+    };
+  }
+  const commands = program2.commands.filter((cmd) => cmd.name() !== "agent-prompt").map(buildCommandSchema);
+  return {
+    executionPolicy: [
+      "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",
+      "Run alchemy --json --no-interactive update-check when you need to detect available CLI upgrades"
+    ],
+    preflight: {
+      command: "alchemy --json setup status",
+      description: "Check auth readiness before first command. If complete is false, follow nextCommands in the response to configure auth."
+    },
+    auth: [
+      {
+        method: "API key",
+        envVar: "ALCHEMY_API_KEY",
+        flag: "--api-key <key>",
+        configKey: "api-key",
+        commandFamilies: [
+          "balance",
+          "tx",
+          "block",
+          "rpc",
+          "trace",
+          "debug",
+          "tokens",
+          "nfts",
+          "transfers",
+          "prices",
+          "portfolio",
+          "simulate",
+          "solana"
+        ]
+      },
+      {
+        method: "Access key",
+        envVar: "ALCHEMY_ACCESS_KEY",
+        flag: "--access-key <key>",
+        configKey: "access-key",
+        commandFamilies: ["apps", "chains", "network list --configured"]
+      },
+      {
+        method: "Webhook API key",
+        envVar: "ALCHEMY_WEBHOOK_API_KEY",
+        flag: "--webhook-api-key <key>",
+        configKey: "webhook-api-key",
+        commandFamilies: ["webhooks"]
+      },
+      {
+        method: "x402 wallet",
+        envVar: "ALCHEMY_WALLET_KEY",
+        flag: "--x402 --wallet-key-file <path>",
+        configKey: "x402",
+        commandFamilies: [
+          "balance",
+          "tx",
+          "block",
+          "rpc",
+          "trace",
+          "debug",
+          "tokens",
+          "nfts",
+          "transfers"
+        ]
+      }
+    ],
+    commands,
+    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",
+      "alchemy --json --no-interactive network list"
+    ],
+    docs: "https://www.alchemy.com/docs"
+  };
+}
+function formatAsSystemPrompt(payload) {
+  const lines = [];
+  lines.push("Alchemy CLI agent instructions");
+  lines.push("==============================");
+  lines.push("");
+  lines.push("Execution policy:");
+  for (const rule of payload.executionPolicy) {
+    lines.push(`  - ${rule}`);
+  }
+  lines.push("");
+  lines.push("Preflight:");
+  lines.push(`  Command: ${payload.preflight.command}`);
+  lines.push(`  ${payload.preflight.description}`);
+  lines.push("");
+  lines.push("Auth methods:");
+  for (const auth of payload.auth) {
+    lines.push(`  ${auth.method}:`);
+    lines.push(`    env:      ${auth.envVar}`);
+    lines.push(`    flag:     ${auth.flag}`);
+    lines.push(`    config:   alchemy config set ${auth.configKey} <value>`);
+    lines.push(`    commands: ${auth.commandFamilies.join(", ")}`);
+  }
+  lines.push("");
+  lines.push("Error codes:");
+  for (const [code, entry] of Object.entries(payload.errors)) {
+    const retry = entry.retryable ? " [retryable]" : "";
+    lines.push(`  ${code} (exit ${entry.exitCode})${retry}: ${entry.recovery}`);
+  }
+  lines.push("");
+  lines.push("Examples:");
+  for (const example of payload.examples) {
+    lines.push(`  ${example}`);
+  }
+  lines.push("");
+  lines.push(`Docs: ${payload.docs}`);
+  lines.push("  For RPC method signatures, parameters, and supported networks.");
+  lines.push("");
+  lines.push(
+    "For full command tree, run: alchemy --json agent-prompt"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function registerAgentPrompt(program2) {
+  program2.command("agent-prompt").description("Emit complete agent/automation usage instructions").action(() => {
+    const payload = buildAgentPrompt(program2);
+    printHuman(formatAsSystemPrompt(payload), payload);
+  });
+}
+
+// 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");
@@ -1646,7 +1863,7 @@ var ROOT_COMMAND_PILLARS = [
   },
   {
     label: "Admin",
-    commands: ["apps", "config", "setup", "version", "help"]
+    commands: ["apps", "config", "setup", "agent-prompt", "update-check", "version", "help"]
   }
 ];
 function formatCommandSignature(sub) {
@@ -1681,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.1.5").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));
   }
@@ -1827,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-3J4EXZMG.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-2ITFWH3B.js");
+    const { startREPL } = await import("./interactive-L7N4HI7K.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {
       }
     });
-    await startREPL(program);
+    await startREPL(program, latestForInteractiveStartup);
     return;
   }
   program.help();
@@ -1874,6 +2120,8 @@ registerApps(program);
 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-2ITFWH3B.js → interactive-L7N4HI7K.js}

@@ -3,7 +3,7 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getRPCNetworkIds,
   getSetupMethod
-} from "./chunk-F7KTEZFZ.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-QKXQW4OF.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",
@@ -100,6 +102,7 @@ var COMMAND_NAMES = [
   "tokens metadata",
   "tokens allowance",
   "tx",
+  "agent-prompt",
   "version",
   "wallet",
   "wallet generate",
@@ -135,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);
@@ -216,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-3J4EXZMG.js → onboarding-YA32OJOT.js}

@@ -5,12 +5,13 @@ import {
   generateAndPersistWallet,
   importAndPersistWallet,
   selectOrCreateApp
-} from "./chunk-PH4BPYSY.js";
+} from "./chunk-XP5KF4W2.js";
 import {
   bold,
   brand,
   brandedHelp,
   dim,
+  getUpdateNoticeLines,
   green,
   load,
   maskIf,
@@ -18,7 +19,7 @@ import {
   promptSelect,
   promptText,
   save
-} from "./chunk-QKXQW4OF.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.1.5",
+  "version": "0.2.1",
   "description": "Alchemy CLI — interact with blockchain data",
   "type": "module",
   "bin": {