@alchemy/cli 0.15.0 → 0.16.0

package/README.md

@@ -182,6 +182,16 @@ Per-command override: pass `--signer <session\|local>` to `evm send`, `evm appro
 | `agent-prompt` | Emits complete agent/automation usage instructions | `alchemy --json --no-interactive agent-prompt` |
 | `version` | Prints CLI version | `alchemy version` |
 
+### Usage API (alpha)
+
+The `usage` commands are in **alpha** — the response shape may change, and
+access is limited to teams enrolled in the Usage API alpha.
+
+```sh
+alchemy --json usage summary
+alchemy usage timeseries --start-date 2026-06-01 --granularity day
+```
+
 ## Flags
 
 ### Global flags
@@ -221,6 +231,7 @@ Additional env vars:
 | Env var | Description |
 |---|---|
 | `ALCHEMY_CONFIG` | Custom path to config file |
+| `ALCHEMY_AUTH_TOKEN` | Admin API auth token override |
 | `ALCHEMY_WALLET_KEY` | EVM wallet private key for x402 auth and local signing |
 | `ALCHEMY_SOLANA_WALLET_KEY` | Solana wallet private key |
 | `ALCHEMY_ACTIVE_SIGNER` | Active EVM signer override (`session` or `local`) |

package/dist/{auth-ZBEPAFEP.js → auth-JHVDOG26.js}

@@ -3,11 +3,11 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   registerAuth,
   selectAppAfterAuth
-} from "./chunk-WDGPT4OT.js";
+} from "./chunk-LRCCQA3I.js";
 import "./chunk-CZWKHYTE.js";
 import "./chunk-EJB4WDTU.js";
-import "./chunk-CXR7CCJ7.js";
-import "./chunk-OIRERSZT.js";
+import "./chunk-FFQ7XKW7.js";
+import "./chunk-GJL52AFY.js";
 import "./chunk-PISUI34T.js";
 import "./chunk-CFIDLPKB.js";
 export {

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

@@ -953,6 +953,7 @@ var AdminClient = class _AdminClient {
   }
   // Test/debug only: used by mock E2E to route admin requests locally.
   static ADMIN_API_BASE_URL_ENV = "ALCHEMY_ADMIN_API_BASE_URL";
+  static USAGE_DEBUG_TEAM_ID_HEADER = "x-alchemy-cli-debug-team-id";
   credential;
   constructor(credential) {
     if (!credential.token.trim()) {
@@ -993,7 +994,7 @@ var AdminClient = class _AdminClient {
       throw errInvalidArgs("Refusing to send credentials over non-HTTPS connection.");
     }
   }
-  async request(method, path, body) {
+  async request(method, path, body, options) {
     const url = `${this.baseURL()}${path}`;
     debug(`${method} ${url}`);
     this.assertSafeRequestTarget(url);
@@ -1003,7 +1004,8 @@ var AdminClient = class _AdminClient {
       headers: {
         Authorization: `Bearer ${this.credential.token}`,
         "Content-Type": "application/json",
-        Accept: "application/json"
+        Accept: "application/json",
+        ...options?.headers
       },
       ...body !== void 0 && { body: JSON.stringify(body) }
     });
@@ -1070,6 +1072,31 @@ var AdminClient = class _AdminClient {
     } while (cursor);
     return { apps, pages };
   }
+  usageDebugHeaders(options) {
+    if (options?.teamId === void 0) return void 0;
+    const baseUrl = new URL(this.baseURL());
+    if (!isLocalhost(baseUrl.hostname)) {
+      throw errInvalidArgs(
+        "--team-id is a temporary debug option and only works with ALCHEMY_ADMIN_API_BASE_URL pointing at localhost."
+      );
+    }
+    return {
+      [_AdminClient.USAGE_DEBUG_TEAM_ID_HEADER]: String(options.teamId)
+    };
+  }
+  async getUsageSummary(options) {
+    return await this.request("GET", "/v1/usage/summary", void 0, {
+      headers: this.usageDebugHeaders(options)
+    });
+  }
+  async getUsageTimeseries(body, options) {
+    return await this.request(
+      "POST",
+      "/v1/usage/time-series",
+      body,
+      { headers: this.usageDebugHeaders(options) }
+    );
+  }
   async getApp(id) {
     const resp = await this.request("GET", `/v1/apps/${id}`);
     return resp.data;
@@ -1621,6 +1648,9 @@ function resolveAppId(program, cfg) {
   return void 0;
 }
 function resolveAuthToken(cfg) {
+  if (process.env.ALCHEMY_AUTH_TOKEN?.trim()) {
+    return process.env.ALCHEMY_AUTH_TOKEN.trim();
+  }
   const config = cfg ?? load();
   if (!config.auth_token?.trim()) return void 0;
   if (config.auth_token_expires_at) {

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

@@ -606,6 +606,7 @@ export {
   green,
   red,
   dim,
+  cyan,
   bold,
   yellow,
   brand,

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

@@ -3,7 +3,7 @@ if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   gasManagerClientFromFlags,
   toAdminNetworkId
-} from "./chunk-CXR7CCJ7.js";
+} from "./chunk-FFQ7XKW7.js";
 import {
   dim,
   green,
@@ -11,7 +11,7 @@ import {
   promptConfirm,
   promptText,
   withSpinner
-} from "./chunk-OIRERSZT.js";
+} from "./chunk-GJL52AFY.js";
 import {
   load,
   save

package/dist/{chunk-WDGPT4OT.js → chunk-LRCCQA3I.js}

@@ -11,7 +11,7 @@ import {
 import {
   AdminClient,
   resolveAuthToken
-} from "./chunk-CXR7CCJ7.js";
+} from "./chunk-FFQ7XKW7.js";
 import {
   bold,
   brand,
@@ -20,7 +20,7 @@ import {
   promptAutocomplete,
   promptText,
   withSpinner
-} from "./chunk-OIRERSZT.js";
+} from "./chunk-GJL52AFY.js";
 import {
   configPath,
   load,

package/dist/{chunk-UL5ZSWTE.js → chunk-N422J6U3.js}

@@ -53,7 +53,7 @@ function semverLT(a, b) {
   return false;
 }
 function currentVersion() {
-  return true ? "0.15.0" : "0.0.0";
+  return true ? "0.16.0" : "0.0.0";
 }
 function toUpdateStatus(latestVersion, checkedAt) {
   const current = currentVersion();

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

@@ -6,7 +6,7 @@ import {
 import {
   resolveAuthToken,
   resolveWalletSession
-} from "./chunk-CXR7CCJ7.js";
+} from "./chunk-FFQ7XKW7.js";
 
 // src/lib/onboarding.ts
 var SETUP_CAPABILITY_ORDER = [

package/dist/index.js

@@ -5,10 +5,10 @@ import {
   errNotLoggedInForPolicyLookup,
   errSponsorshipNeedsPolicy,
   selectOrCreatePolicy
-} from "./chunk-M7HFRKW6.js";
+} from "./chunk-HPRJEGSP.js";
 import {
   registerAuth
-} from "./chunk-WDGPT4OT.js";
+} from "./chunk-LRCCQA3I.js";
 import {
   openBrowser
 } from "./chunk-CZWKHYTE.js";
@@ -18,7 +18,7 @@ import {
   getSetupStatus,
   isSetupComplete,
   shouldRunOnboarding
-} from "./chunk-RQDWIB62.js";
+} from "./chunk-Q2VRERYE.js";
 import {
   isInteractiveAllowed
 } from "./chunk-EJB4WDTU.js";
@@ -63,16 +63,17 @@ import {
   updateSession,
   validateNetwork,
   walletNetworkToChain
-} from "./chunk-CXR7CCJ7.js";
+} from "./chunk-FFQ7XKW7.js";
 import {
   getAvailableUpdate,
   getUpdateStatus,
   printUpdateNotice
-} from "./chunk-UL5ZSWTE.js";
+} from "./chunk-N422J6U3.js";
 import {
   bold,
   brand,
   brandedHelp,
+  cyan,
   dim,
   emptyState,
   etherscanTxURL,
@@ -92,7 +93,7 @@ import {
   weiToEth,
   withSpinner,
   yellow
-} from "./chunk-OIRERSZT.js";
+} from "./chunk-GJL52AFY.js";
 import {
   KEY_MAP,
   configDir,
@@ -148,7 +149,7 @@ import {
 } from "./chunk-CFIDLPKB.js";
 
 // src/index.ts
-import { Command, Help } from "commander";
+import { Command as Command2, Help } from "commander";
 
 // src/lib/ens.ts
 import { keccak_256 } from "@noble/hashes/sha3.js";
@@ -582,8 +583,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-UNNIF63S.js");
-      const { resolveNetwork: resolveNetwork2 } = await import("./resolve-IRTGQL4A.js");
+      const { selectOrCreatePolicy: selectOrCreatePolicy2 } = await import("./policy-prompt-DRO7Q5VI.js");
+      const { resolveNetwork: resolveNetwork2 } = await import("./resolve-B64J4LR6.js");
       const network = resolveNetwork2(program2);
       await selectOrCreatePolicy2({
         flavor: "sponsorship",
@@ -637,8 +638,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-UNNIF63S.js");
-      const { resolveSolanaNetwork: resolveSolanaNetwork2 } = await import("./resolve-IRTGQL4A.js");
+      const { selectOrCreatePolicy: selectOrCreatePolicy2 } = await import("./policy-prompt-DRO7Q5VI.js");
+      const { resolveSolanaNetwork: resolveSolanaNetwork2 } = await import("./resolve-B64J4LR6.js");
       const network = resolveSolanaNetwork2(program2);
       await selectOrCreatePolicy2({
         flavor: "solana",
@@ -695,7 +696,7 @@ function registerConfig(program2) {
       printJSON(toMap(cfg));
       return;
     }
-    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-IRTGQL4A.js");
+    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-B64J4LR6.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 = [
@@ -1370,6 +1371,455 @@ function registerApps(program2) {
   });
 }
 
+// src/commands/usage.ts
+import { Option } from "commander";
+
+// src/lib/usage-format.ts
+var BLOCKS = [" ", "\u258F", "\u258E", "\u258D", "\u258C", "\u258B", "\u258A", "\u2589", "\u2588"];
+var SPARKS = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+var MAX_ROWS = 31;
+function asRecord(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function asStringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  const strings = value.filter((item) => typeof item === "string");
+  return strings.length > 0 ? strings : void 0;
+}
+function parsePoint(value) {
+  const record = asRecord(value);
+  if (!record) return void 0;
+  const dimensions = asRecord(record.dimensions);
+  return {
+    startTime: typeof record.startTime === "string" ? record.startTime : void 0,
+    endTime: typeof record.endTime === "string" ? record.endTime : void 0,
+    isPartial: typeof record.isPartial === "boolean" ? record.isPartial : void 0,
+    dimensions: dimensions ? Object.fromEntries(
+      Object.entries(dimensions).filter((entry) => typeof entry[1] === "string")
+    ) : void 0,
+    amount: typeof record.amount === "string" ? record.amount : void 0,
+    unit: typeof record.unit === "string" ? record.unit : void 0,
+    usd: typeof record.usd === "string" ? record.usd : void 0
+  };
+}
+function getUsageTimeSeriesData(result) {
+  const root = asRecord(result);
+  const envelope = asRecord(root?.data);
+  const points = Array.isArray(envelope?.data) ? envelope.data.map(parsePoint).filter((point) => Boolean(point)) : void 0;
+  if (!envelope || !points) return void 0;
+  const query = asRecord(envelope.query);
+  const freshness = asRecord(envelope.freshness);
+  return {
+    query: query ? {
+      startTime: typeof query.startTime === "string" ? query.startTime : void 0,
+      endTime: typeof query.endTime === "string" ? query.endTime : void 0,
+      metrics: asStringArray(query.metrics),
+      groupBy: asStringArray(query.groupBy)
+    } : void 0,
+    freshness: freshness ? {
+      dataThrough: typeof freshness.dataThrough === "string" ? freshness.dataThrough : void 0,
+      containsPartialToday: typeof freshness.containsPartialToday === "boolean" ? freshness.containsPartialToday : void 0
+    } : void 0,
+    data: points
+  };
+}
+function finiteNumber(value) {
+  if (!value) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function chooseValueField(data) {
+  const metrics = data.query?.metrics ?? [];
+  const hasAmount = data.data.some((point) => finiteNumber(point.amount) !== void 0);
+  const hasUsd = data.data.some((point) => finiteNumber(point.usd) !== void 0);
+  if (metrics.includes("usd") && !metrics.includes("amount") && hasUsd) return "usd";
+  if (hasAmount) return "amount";
+  if (hasUsd) return "usd";
+  return void 0;
+}
+function dateLabel(value) {
+  if (!value) return "unknown";
+  return value.slice(0, 10);
+}
+function aggregateByDay(points, field) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const point of points) {
+    const value = finiteNumber(point[field]);
+    if (value === void 0) continue;
+    const date = dateLabel(point.startTime);
+    const existing = buckets.get(date);
+    if (existing) {
+      existing.value += value;
+      existing.isPartial = existing.isPartial || point.isPartial === true;
+    } else {
+      buckets.set(date, {
+        date,
+        value,
+        isPartial: point.isPartial === true
+      });
+    }
+  }
+  return [...buckets.values()].sort((a, b) => a.date.localeCompare(b.date));
+}
+function formatNumber(value, field) {
+  return new Intl.NumberFormat("en-US", {
+    maximumFractionDigits: field === "usd" ? 2 : 3
+  }).format(value);
+}
+function metricLabel(args) {
+  if (args.field === "usd") return "USD";
+  return args.unit ?? "usage";
+}
+function bar(args) {
+  if (args.max <= 0 || args.value <= 0) return dim(" ".repeat(args.width));
+  const filled = args.value / args.max * args.width;
+  const full = Math.floor(filled);
+  const partial = Math.round((filled - full) * 8);
+  const partialBlock = partial > 0 ? BLOCKS[partial] : "";
+  const barText = "\u2588".repeat(full) + partialBlock;
+  const padding = " ".repeat(Math.max(0, args.width - full - (partial > 0 ? 1 : 0)));
+  return cyan(barText) + dim(padding);
+}
+function sparkline(values) {
+  const max = Math.max(...values, 1);
+  const line = values.map((value) => SPARKS[Math.round(value / max * 7)] ?? SPARKS[0]).join("");
+  return green(line);
+}
+function labelWidth(labels) {
+  return Math.min(Math.max(...labels.map((label) => label.length), 4), 18);
+}
+function formatRange(data, buckets) {
+  const start = data.query?.startTime ? dateLabel(data.query.startTime) : buckets[0]?.date;
+  const end = data.query?.endTime ? dateLabel(data.query.endTime) : buckets[buckets.length - 1]?.date;
+  return start && end ? `${start} -> ${end}` : "unknown range";
+}
+function dimensionLabel(point) {
+  const entries = Object.entries(point.dimensions ?? {}).filter(([, value]) => value).map(([key, value]) => `${key}=${value}`);
+  return entries.length > 0 ? entries.join(", ") : void 0;
+}
+function aggregateDimensions(points, field) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const point of points) {
+    const label = dimensionLabel(point);
+    const value = finiteNumber(point[field]);
+    if (!label || value === void 0) continue;
+    totals.set(label, (totals.get(label) ?? 0) + value);
+  }
+  return [...totals.entries()].map(([label, value]) => ({ label, value })).sort((a, b) => b.value - a.value).slice(0, 6);
+}
+function formatUsageTimeSeriesResult(result) {
+  const data = getUsageTimeSeriesData(result);
+  if (!data || data.data.length === 0) return null;
+  const field = chooseValueField(data);
+  if (!field) return null;
+  const buckets = aggregateByDay(data.data, field);
+  if (buckets.length === 0) return null;
+  const unit = metricLabel({
+    field,
+    unit: data.data.find((point) => point.unit)?.unit
+  });
+  const values = buckets.map((bucket) => bucket.value);
+  const total = values.reduce((sum, value) => sum + value, 0);
+  const peak = buckets.reduce(
+    (best, bucket) => bucket.value > best.value ? bucket : best
+  );
+  const max = Math.max(...values, 1);
+  const shownBuckets = buckets.slice(0, MAX_ROWS);
+  const width = labelWidth(shownBuckets.map((bucket) => bucket.date));
+  const lines = [];
+  lines.push("");
+  lines.push(`  ${brand(bold("Usage time series"))}`);
+  lines.push(`  ${dim(formatRange(data, buckets))}  ${dim("metric")} ${field}`);
+  lines.push("");
+  lines.push(
+    `  ${dim("total")} ${green(formatNumber(total, field))} ${dim(unit)}  ${dim("peak")} ${yellow(`${peak.date} ${formatNumber(peak.value, field)}`)}`
+  );
+  if (data.freshness?.dataThrough) {
+    const partial = data.freshness.containsPartialToday ? " partial today" : "";
+    lines.push(`  ${dim("fresh through")} ${dateLabel(data.freshness.dataThrough)}${dim(partial)}`);
+  }
+  lines.push("");
+  lines.push(`  ${sparkline(values)}`);
+  lines.push("");
+  for (const bucket of shownBuckets) {
+    const date = bucket.date.padEnd(width);
+    const partial = bucket.isPartial ? " *" : "  ";
+    const value = formatNumber(bucket.value, field).padStart(12);
+    lines.push(
+      `  ${dim(date)}${partial} ${value} ${dim(unit)}  ${bar({
+        value: bucket.value,
+        max,
+        width: 28
+      })}`
+    );
+  }
+  if (buckets.length > shownBuckets.length) {
+    lines.push(
+      `  ${dim(`showing ${shownBuckets.length} of ${buckets.length} days; use --json for full data`)}`
+    );
+  }
+  if (buckets.some((bucket) => bucket.isPartial)) {
+    lines.push(`  ${dim("* partial bucket")}`);
+  }
+  const dimensions = aggregateDimensions(data.data, field);
+  if (dimensions.length > 0) {
+    const dimensionMax = Math.max(...dimensions.map((item) => item.value), 1);
+    const dimensionWidth = labelWidth(dimensions.map((item) => item.label));
+    lines.push("");
+    lines.push(`  ${brand(bold("Top dimensions"))}`);
+    for (const item of dimensions) {
+      const label = item.label.length > dimensionWidth ? `${item.label.slice(0, dimensionWidth - 1)}\u2026` : item.label.padEnd(dimensionWidth);
+      lines.push(
+        `  ${dim(label)}  ${formatNumber(item.value, field).padStart(12)} ${dim(unit)}  ${bar({
+          value: item.value,
+          max: dimensionMax,
+          width: 20
+        })}`
+      );
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/usage.ts
+var DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+var DATETIME_WITH_TIMEZONE_RE = /^\d{4}-\d{2}-\d{2}T.+(Z|[+-]\d{2}:\d{2})$/;
+var TEAM_ID_RE = /^\d+$/;
+var VALID_METRICS = /* @__PURE__ */ new Set(["amount", "usd"]);
+var VALID_GROUP_BY = /* @__PURE__ */ new Set([
+  "requestType",
+  "app",
+  "network",
+  "method"
+]);
+var VALID_REQUEST_TYPES = /* @__PURE__ */ new Set([
+  "http",
+  "websocket",
+  "webhook",
+  "grpc"
+]);
+function parseBodyJSON(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw errInvalidArgs("--body must be valid JSON.");
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw errInvalidArgs("--body must be a JSON object.");
+  }
+  return parsed;
+}
+function splitCommaList2(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+function assertAllowedValues(values, allowed, flagName) {
+  for (const value of values ?? []) {
+    if (!allowed.has(value)) {
+      throw errInvalidArgs(
+        `${flagName} contains unsupported value '${value}'.`
+      );
+    }
+  }
+}
+function debugTeamIdOption() {
+  return new Option(
+    "--team-id <id>",
+    "Temporary local usage API team override"
+  ).hideHelp();
+}
+function parseTeamId(value) {
+  if (value === void 0) return void 0;
+  if (!TEAM_ID_RE.test(value)) {
+    throw errInvalidArgs("--team-id must be a positive integer.");
+  }
+  const teamId = Number(value);
+  if (!Number.isSafeInteger(teamId) || teamId <= 0) {
+    throw errInvalidArgs("--team-id must be a positive integer.");
+  }
+  return teamId;
+}
+function buildUsageRequestOptions(opts) {
+  const teamId = parseTeamId(opts.teamId);
+  return teamId === void 0 ? void 0 : { teamId };
+}
+function normalizeDateTime(value, flagName) {
+  if (!value) return void 0;
+  if (DATE_ONLY_RE.test(value)) {
+    const date2 = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(date2.getTime()) || date2.toISOString().slice(0, 10) !== value) {
+      throw errInvalidArgs(`${flagName} must be a valid date or datetime.`);
+    }
+    return `${value}T00:00:00.000Z`;
+  }
+  if (!DATETIME_WITH_TIMEZONE_RE.test(value)) {
+    throw errInvalidArgs(
+      `${flagName} must be YYYY-MM-DD or an ISO datetime with a timezone.`
+    );
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw errInvalidArgs(`${flagName} must be a valid date or datetime.`);
+  }
+  return date.toISOString();
+}
+function hasBuilderOptions(opts) {
+  return Object.entries(opts).some(
+    ([key, value]) => key !== "body" && key !== "teamId" && value !== void 0
+  );
+}
+function buildTimeseriesRequest(opts) {
+  if (opts.body) {
+    if (hasBuilderOptions(opts)) {
+      throw errInvalidArgs("--body cannot be combined with other time series flags.");
+    }
+    return parseBodyJSON(opts.body);
+  }
+  if (opts.startDate && opts.startTime) {
+    throw errInvalidArgs("Pass either --start-date or --start-time, not both.");
+  }
+  if (opts.endDate && opts.endTime) {
+    throw errInvalidArgs("Pass either --end-date or --end-time, not both.");
+  }
+  const startTime = normalizeDateTime(
+    opts.startTime ?? opts.startDate,
+    opts.startTime ? "--start-time" : "--start-date"
+  );
+  const endTime = normalizeDateTime(
+    opts.endTime ?? opts.endDate,
+    opts.endTime ? "--end-time" : "--end-date"
+  ) ?? (/* @__PURE__ */ new Date()).toISOString();
+  if (!startTime) {
+    throw errInvalidArgs(
+      "Usage time series requires --start-date or --start-time, or --body."
+    );
+  }
+  const products = splitCommaList2(opts.products);
+  const metrics = splitCommaList2(opts.metrics);
+  const appIds = splitCommaList2(opts.appIds);
+  const networks = splitCommaList2(opts.networks);
+  const methods = splitCommaList2(opts.methods);
+  const requestTypes = splitCommaList2(opts.requestTypes);
+  const groupBy = splitCommaList2(opts.groupBy);
+  assertAllowedValues(metrics, VALID_METRICS, "--metrics");
+  assertAllowedValues(requestTypes, VALID_REQUEST_TYPES, "--request-types");
+  assertAllowedValues(groupBy, VALID_GROUP_BY, "--group-by");
+  if (groupBy && groupBy.length > 1) {
+    throw errInvalidArgs("--group-by accepts at most one dimension.");
+  }
+  const granularity = opts.granularity ?? "day";
+  if (granularity !== "day" && granularity !== "hour") {
+    throw errInvalidArgs("--granularity must be 'hour' or 'day'.");
+  }
+  const filters = {
+    ...appIds && { appIds },
+    ...networks && { networks },
+    ...methods && { methods },
+    ...requestTypes && { requestTypes }
+  };
+  return {
+    startTime,
+    endTime,
+    granularity,
+    ...products && { products },
+    ...metrics && { metrics },
+    ...Object.keys(filters).length > 0 && { filters },
+    ...groupBy && { groupBy }
+  };
+}
+function printUsageResult(result) {
+  if (isJSONMode()) {
+    printJSON(result);
+    return;
+  }
+  printSyntaxJSON(result);
+}
+function printUsageTimeseriesResult(result) {
+  if (isJSONMode()) {
+    printJSON(result);
+    return;
+  }
+  const formatted = formatUsageTimeSeriesResult(result);
+  if (formatted) {
+    printHuman(formatted, result);
+    return;
+  }
+  printSyntaxJSON(result);
+}
+function registerUsage(program2) {
+  const cmd = program2.command("usage").description("View Alchemy usage data (alpha)").addHelpText(
+    "after",
+    () => (
+      // Skip in JSON help mode so structured output stays valid JSON.
+      isJSONMode() ? "" : [
+        "",
+        "Alpha: the Usage API is in early access. The response shape may",
+        "change, and access is limited to teams enrolled in the alpha."
+      ].join("\n")
+    )
+  );
+  cmd.command("summary").description("Get account usage summary").addOption(debugTeamIdOption()).action(async (opts) => {
+    try {
+      const admin = adminClientFromFlags(program2);
+      const usageOptions = buildUsageRequestOptions(opts);
+      const result = await withSpinner(
+        "Fetching usage summary...",
+        "Usage summary fetched",
+        () => usageOptions ? admin.getUsageSummary(usageOptions) : admin.getUsageSummary()
+      );
+      printUsageResult(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+  cmd.command("timeseries").alias("time-series").description("Get account usage time series data").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").option("--start-time <datetime>", "Start time as an ISO datetime").option("--end-time <datetime>", "End time as an ISO datetime").option("--products <products>", "Comma-separated BillingProduct enum names").option("--metrics <metrics>", "Comma-separated metrics: amount,usd").option("--app-ids <ids>", "Filter by app IDs (comma-separated)").option(
+    "--networks <networks>",
+    "Filter by networks (comma-separated), e.g. eth-mainnet,base-mainnet"
+  ).option("--methods <methods>", "Filter by methods (comma-separated), e.g. eth_getLogs").option(
+    "--request-types <types>",
+    "Filter by request types (comma-separated): http, websocket, webhook, grpc"
+  ).option(
+    "--group-by <dimension>",
+    "Group by one dimension: requestType, app, network, method"
+  ).option("--granularity <granularity>", "Granularity: hour or day (default day)").option("--body <json>", "Raw time series request JSON body").addOption(debugTeamIdOption()).addHelpText(
+    "after",
+    () => (
+      // Skip in JSON help mode so the structured output stays valid JSON.
+      isJSONMode() ? "" : [
+        "",
+        "Filters (optional, comma-separated, combined with AND):",
+        "  --app-ids        one or more app IDs",
+        "  --networks       network slugs, e.g. eth-mainnet,base-mainnet",
+        "  --methods        RPC/REST methods, e.g. eth_getLogs",
+        "  --request-types  http, websocket, webhook, grpc",
+        "",
+        "Group by (choose one dimension):",
+        "  requestType | app | network | method"
+      ].join("\n")
+    )
+  ).action(async (opts) => {
+    try {
+      const admin = adminClientFromFlags(program2);
+      const body = buildTimeseriesRequest(opts);
+      const usageOptions = buildUsageRequestOptions(opts);
+      const result = await withSpinner(
+        "Fetching usage time series...",
+        "Usage time series fetched",
+        () => usageOptions ? admin.getUsageTimeseries(body, usageOptions) : admin.getUsageTimeseries(body)
+      );
+      printUsageTimeseriesResult(result);
+    } catch (err) {
+      exitWithError(err);
+    }
+  });
+}
+
 // src/commands/wallet.ts
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
 import { join, dirname } from "path";
@@ -3371,7 +3821,7 @@ function registerWebhooks(program2) {
   });
 }
 
-// src/lib/solana-rpc.ts
+// ../../packages/sdk/dist/solana/index.js
 var SOLANA_DAS_METHODS = /* @__PURE__ */ new Set([
   "getAsset",
   "getAssetsByOwner",
@@ -3385,7 +3835,37 @@ var SOLANA_DAS_METHODS = /* @__PURE__ */ new Set([
   "getAssetSignatures",
   "getNftEditions"
 ]);
+var SOLANA_DAS_PAYWALL_PATTERN = /\b(free tier|payg|paid tier|paid plan|upgrade|plan does not|current plan|not available on your plan)\b/i;
+function isSolanaDasMethod(method) {
+  return SOLANA_DAS_METHODS.has(method);
+}
+function solanaRpcFamilyForMethod(method) {
+  return isSolanaDasMethod(method) ? "das" : "rpc";
+}
+function classifySolanaDasPaywallError(err) {
+  const details = errorText(err);
+  if (!SOLANA_DAS_PAYWALL_PATTERN.test(details)) {
+    return void 0;
+  }
+  return {
+    message: "Solana DAS request requires a paid Alchemy plan.",
+    hint: "Upgrade your app to PAYG or use a plan with Solana DAS access at https://dashboard.alchemy.com/.",
+    ...details && { details }
+  };
+}
 function errorText(err) {
+  if (err instanceof Error) {
+    const details = stringValue(err.details);
+    return [err.message, details].filter(Boolean).join(" ");
+  }
+  return String(err);
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/lib/solana-rpc.ts
+function errorText2(err) {
   if (err instanceof CLIError) {
     return [err.message, err.details].filter(Boolean).join(" ");
   }
@@ -3394,22 +3874,19 @@ function errorText(err) {
   }
   return String(err);
 }
-function solanaRpcFamilyForMethod(method) {
-  return SOLANA_DAS_METHODS.has(method) ? "das" : "rpc";
-}
 function normalizeSolanaDasPaywallError(err) {
   if (err instanceof CLIError && err.code === ErrorCode.PAYMENT_REQUIRED) {
     return err;
   }
-  const detail = errorText(err);
-  if (!/\b(free tier|payg|paid tier|paid plan|upgrade|plan does not|current plan|not available on your plan)\b/i.test(detail)) {
+  const paywall = classifySolanaDasPaywallError(err);
+  if (!paywall) {
     return null;
   }
   return new CLIError(
     ErrorCode.PAYMENT_REQUIRED,
-    "Solana DAS request requires a paid Alchemy plan.",
-    "Upgrade your app to PAYG or use a plan with Solana DAS access at https://dashboard.alchemy.com/.",
-    detail || void 0
+    paywall.message,
+    paywall.hint,
+    paywall.details
   );
 }
 async function callSolana(client, family, method, params) {
@@ -3420,7 +3897,7 @@ async function callSolana(client, family, method, params) {
     debug(`solana ${family} ${method} ok ${Date.now() - startedAt}ms`);
     return result;
   } catch (err) {
-    debug(`solana ${family} ${method} failed ${Date.now() - startedAt}ms`, errorText(err));
+    debug(`solana ${family} ${method} failed ${Date.now() - startedAt}ms`, errorText2(err));
     throw err;
   }
 }
@@ -5832,6 +6309,49 @@ var PortfolioApiClient = class {
     return dataPost(portfolioBaseUrl(this.options), this.apiKey, path, body, this.options);
   }
 };
+var PORTFOLIO_BALANCE_FIELD_NAMES = /* @__PURE__ */ new Set([
+  "balance",
+  "tokenbalance",
+  "rawbalance",
+  "rawtokenbalance",
+  "amount"
+]);
+function limitPortfolioPayload(value, limit) {
+  if (limit === void 0)
+    return value;
+  if (Array.isArray(value)) {
+    return value.slice(0, limit).map((item) => limitPortfolioPayload(item, limit));
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+      key,
+      limitPortfolioPayload(nested, limit)
+    ]));
+  }
+  return value;
+}
+function normalizePortfolioOutput(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizePortfolioOutput);
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  const decimals = decimalsForRecord(value);
+  const output = {};
+  for (const [key, nested] of Object.entries(value)) {
+    output[key] = normalizePortfolioOutput(nested);
+    if (typeof nested !== "string" || !shouldNormalizeBalanceField(key) || !isHexQuantity(nested)) {
+      continue;
+    }
+    const raw = BigInt(nested);
+    output[`${key}Decimal`] = raw.toString();
+    if (decimals !== void 0) {
+      output[`${key}Formatted`] = formatRawAmount(raw, decimals);
+    }
+  }
+  return output;
+}
 async function dataFetch(url, method, body, options) {
   const fetchFn = options.fetchFn ?? fetch;
   const resp = await fetchFn(url, {
@@ -5850,6 +6370,48 @@ async function dataFetch(url, method, body, options) {
   }
   return resp;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHexQuantity(value) {
+  return /^0x[0-9a-f]+$/i.test(value);
+}
+function parseDecimals2(value) {
+  const decimals = typeof value === "number" ? value : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : void 0;
+  if (decimals === void 0 || !Number.isInteger(decimals) || decimals < 0 || decimals > 255) {
+    return void 0;
+  }
+  return decimals;
+}
+function decimalsForRecord(value) {
+  const direct = parseDecimals2(value.decimals);
+  if (direct !== void 0)
+    return direct;
+  for (const key of ["tokenMetadata", "metadata", "token"]) {
+    const nested = value[key];
+    if (isRecord(nested)) {
+      const decimals = parseDecimals2(nested.decimals);
+      if (decimals !== void 0)
+        return decimals;
+    }
+  }
+  return void 0;
+}
+function formatRawAmount(raw, decimals) {
+  if (decimals === 0)
+    return raw.toString();
+  const divisor = 10n ** BigInt(decimals);
+  const whole = raw / divisor;
+  const fraction = raw % divisor;
+  if (fraction === 0n)
+    return whole.toString();
+  const fractionText = fraction.toString().padStart(decimals, "0").replace(/0+$/, "");
+  return `${whole}.${fractionText}`;
+}
+function shouldNormalizeBalanceField(key) {
+  const normalized = key.toLowerCase();
+  return PORTFOLIO_BALANCE_FIELD_NAMES.has(normalized) || normalized.endsWith("balance");
+}
 
 // ../../packages/sdk/dist/surfaces/index.js
 var RPC_API_SURFACE = [
@@ -6378,7 +6940,7 @@ var AGENT_PROMPT_SCOPES = [
   "xchain"
 ];
 var SCOPE_COMMAND_PATHS = {
-  app: ["app", "auth", "config"],
+  app: ["app", "usage", "auth", "config"],
   data: ["evm data", "evm logs", "evm block", "evm tx", "evm receipt"],
   evm: ["evm"],
   solana: ["solana"],
@@ -6395,7 +6957,7 @@ var SCOPE_COMMAND_PATHS = {
   xchain: ["xchain"]
 };
 var SCOPE_EXAMPLE_MATCHERS = {
-  app: [" app ", " auth ", " config "],
+  app: [" app ", " usage ", " auth ", " config "],
   data: [" evm data ", " evm logs ", " evm block ", " evm tx ", " evm receipt "],
   evm: [" evm "],
   solana: [" solana "],
@@ -6441,7 +7003,7 @@ function buildCommandSchema(cmd) {
       required: a.required
     }));
   }
-  const opts = cmd.options;
+  const opts = visibleOptions(cmd);
   if (opts.length > 0) {
     schema.options = opts.map((o) => ({
       flags: o.flags,
@@ -6456,6 +7018,11 @@ function buildCommandSchema(cmd) {
   }
   return schema;
 }
+function visibleOptions(cmd) {
+  return cmd.options.filter((option) => {
+    return !option.hidden;
+  });
+}
 function commandMatchesPath(cmd, path) {
   if (path[0] !== cmd.name) return null;
   if (path.length === 1) return cmd;
@@ -6507,6 +7074,7 @@ function applyScope(payload, scope) {
   );
 }
 function buildAgentPrompt(program2) {
+  const hasUsageCommand = program2.commands.some((cmd) => cmd.name() === "usage");
   const errors = {};
   for (const [code, exitCode] of Object.entries(EXIT_CODES)) {
     errors[code] = {
@@ -6516,6 +7084,24 @@ function buildAgentPrompt(program2) {
     };
   }
   const commands = program2.commands.filter((cmd) => cmd.name() !== "agent-prompt").map(buildCommandSchema);
+  const examples = [
+    "alchemy --json --no-interactive config status",
+    "alchemy --json --no-interactive update-check",
+    "alchemy --json --no-interactive evm data balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --api-key $ALCHEMY_API_KEY -n eth-mainnet",
+    "alchemy --json --no-interactive app list",
+    ...hasUsageCommand ? [
+      "alchemy --json --no-interactive usage summary",
+      "alchemy --json --no-interactive usage timeseries --start-date 2026-06-01 --end-date 2026-06-08"
+    ] : [],
+    "alchemy --json --no-interactive evm rpc eth_blockNumber --api-key $ALCHEMY_API_KEY -n eth-mainnet",
+    "alchemy --json --no-interactive evm network list",
+    "alchemy --json --no-interactive evm send 0xRecipient 0.001 --dry-run -n eth-sepolia",
+    `alchemy --json --no-interactive evm contract read 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "balanceOf(address)(uint256)" --args '["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]' -n eth-mainnet`,
+    "alchemy --json --no-interactive evm swap quote --from 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE --to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 1.0 --from-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n eth-mainnet",
+    "alchemy --json --no-interactive evm logs --from-block latest --limit 25 -n eth-mainnet",
+    "alchemy --json --no-interactive evm block latest --summary -n eth-mainnet",
+    "alchemy --json --no-interactive evm status 0xCallId -n eth-mainnet"
+  ];
   return {
     executionPolicy: [
       "Always pass --json --no-interactive",
@@ -6585,9 +7171,15 @@ function buildAgentPrompt(program2) {
       },
       {
         method: "Alchemy login",
+        envVar: "ALCHEMY_AUTH_TOKEN",
         setup: "alchemy auth login",
-        commandFamilies: ["app", "evm network", "gas-manager"],
-        notes: "Admin surfaces use the browser login session stored by `alchemy auth login`."
+        commandFamilies: [
+          "app",
+          ...hasUsageCommand ? ["usage"] : [],
+          "evm network",
+          "gas-manager"
+        ],
+        notes: "Admin surfaces use the browser login session stored by `alchemy auth login`, or `ALCHEMY_AUTH_TOKEN` when set."
       },
       {
         method: "Webhook API key",
@@ -6641,20 +7233,7 @@ function buildAgentPrompt(program2) {
     ],
     commands,
     errors,
-    examples: [
-      "alchemy --json --no-interactive config status",
-      "alchemy --json --no-interactive update-check",
-      "alchemy --json --no-interactive evm data balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --api-key $ALCHEMY_API_KEY -n eth-mainnet",
-      "alchemy --json --no-interactive app list",
-      "alchemy --json --no-interactive evm rpc eth_blockNumber --api-key $ALCHEMY_API_KEY -n eth-mainnet",
-      "alchemy --json --no-interactive evm network list",
-      "alchemy --json --no-interactive evm send 0xRecipient 0.001 --dry-run -n eth-sepolia",
-      `alchemy --json --no-interactive evm contract read 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "balanceOf(address)(uint256)" --args '["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]' -n eth-mainnet`,
-      "alchemy --json --no-interactive evm swap quote --from 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE --to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 1.0 --from-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 -n eth-mainnet",
-      "alchemy --json --no-interactive evm logs --from-block latest --limit 25 -n eth-mainnet",
-      "alchemy --json --no-interactive evm block latest --summary -n eth-mainnet",
-      "alchemy --json --no-interactive evm status 0xCallId -n eth-mainnet"
-    ],
+    examples,
     docs: "https://www.alchemy.com/docs"
   };
 }
@@ -6877,7 +7456,7 @@ function registrySymbolSuggestions(network) {
 }
 
 // src/lib/preflight-errors.ts
-function errorText2(err) {
+function errorText3(err) {
   if (err instanceof CLIError) {
     return [err.message, err.details].filter(Boolean).join(" ");
   }
@@ -6912,7 +7491,7 @@ function normalizePreflightRevertError(err) {
   if (err instanceof CLIError && err.code === ErrorCode.PREFLIGHT_REVERT) {
     return err;
   }
-  const detail = errorText2(err);
+  const detail = errorText3(err);
   const reason = extractRevertReason(detail);
   if (!reason) return null;
   return errPreflightRevert(reason, detail || void 0);
@@ -8250,13 +8829,6 @@ Examples:
 }
 
 // src/commands/portfolio.ts
-var BALANCE_FIELD_NAMES = /* @__PURE__ */ new Set([
-  "balance",
-  "tokenbalance",
-  "rawbalance",
-  "rawtokenbalance",
-  "amount"
-]);
 async function runDataCall(program2, title, path, body) {
   const x402 = resolveX402Client(program2);
   return withSpinner(
@@ -8265,85 +8837,10 @@ async function runDataCall(program2, title, path, body) {
     () => x402 ? x402.callRest(`data/v1${path}`, { method: "POST", body }) : callApiData(resolveAPIKey(program2), path, { method: "POST", body })
   );
 }
-function limitPayload(value, limit) {
-  if (limit === void 0) return value;
-  if (Array.isArray(value)) {
-    return value.slice(0, limit).map((item) => limitPayload(item, limit));
-  }
-  if (isRecord(value)) {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, nested]) => [
-        key,
-        limitPayload(nested, limit)
-      ])
-    );
-  }
-  return value;
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isHexQuantity(value) {
-  return /^0x[0-9a-f]+$/i.test(value);
-}
-function parseDecimals2(value) {
-  const decimals = typeof value === "number" ? value : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : void 0;
-  if (decimals === void 0 || !Number.isInteger(decimals) || decimals < 0 || decimals > 255) {
-    return void 0;
-  }
-  return decimals;
-}
-function decimalsForRecord(value) {
-  const direct = parseDecimals2(value.decimals);
-  if (direct !== void 0) return direct;
-  for (const key of ["tokenMetadata", "metadata", "token"]) {
-    const nested = value[key];
-    if (isRecord(nested)) {
-      const decimals = parseDecimals2(nested.decimals);
-      if (decimals !== void 0) return decimals;
-    }
-  }
-  return void 0;
-}
-function formatRawAmount(raw, decimals) {
-  if (decimals === 0) return raw.toString();
-  const divisor = 10n ** BigInt(decimals);
-  const whole = raw / divisor;
-  const fraction = raw % divisor;
-  if (fraction === 0n) return whole.toString();
-  const fractionText = fraction.toString().padStart(decimals, "0").replace(/0+$/, "");
-  return `${whole}.${fractionText}`;
-}
-function shouldNormalizeBalanceField(key) {
-  const normalized = key.toLowerCase();
-  return BALANCE_FIELD_NAMES.has(normalized) || normalized.endsWith("balance");
-}
-function normalizePortfolioOutput(value) {
-  if (Array.isArray(value)) {
-    return value.map(normalizePortfolioOutput);
-  }
-  if (!isRecord(value)) {
-    return value;
-  }
-  const decimals = decimalsForRecord(value);
-  const output = {};
-  for (const [key, nested] of Object.entries(value)) {
-    output[key] = normalizePortfolioOutput(nested);
-    if (typeof nested !== "string" || !shouldNormalizeBalanceField(key) || !isHexQuantity(nested)) {
-      continue;
-    }
-    const raw = BigInt(nested);
-    output[`${key}Decimal`] = raw.toString();
-    if (decimals !== void 0) {
-      output[`${key}Formatted`] = formatRawAmount(raw, decimals);
-    }
-  }
-  return output;
-}
 async function runPortfolioCommand(program2, title, path, opts) {
   const limit = parseOptionalInt(opts.limit, "--limit");
   const result = await runDataCall(program2, title, path, JSON.parse(opts.body));
-  const output = normalizePortfolioOutput(limitPayload(result, limit));
+  const output = normalizePortfolioOutput(limitPortfolioPayload(result, limit));
   if (isJSONMode()) printJSON(output);
   else printSyntaxJSON(output);
 }
@@ -9001,7 +9498,7 @@ function buildWalletQuoteClient(program2, address3) {
 }
 
 // src/lib/quote-errors.ts
-function errorText3(err) {
+function errorText4(err) {
   if (err instanceof CLIError) {
     return [err.message, err.details].filter(Boolean).join(" ");
   }
@@ -9059,7 +9556,7 @@ function normalizeQuoteError(err, flow) {
   if (err instanceof CLIError && err.code !== ErrorCode.RPC_ERROR && err.code !== ErrorCode.INTERNAL_ERROR) {
     return err;
   }
-  const detail = errorText3(err);
+  const detail = errorText4(err);
   const cause = classifyQuoteFailure(detail);
   return new CLIError(
     ErrorCode.QUOTE_FAILED,
@@ -10648,7 +11145,7 @@ var ROOT_COMMAND_PILLARS = [
   },
   {
     label: "Account & Platform",
-    commands: ["auth", "wallet", "app", "webhook", "config"]
+    commands: ["auth", "wallet", "app", "usage", "webhook", "config"]
   },
   {
     label: "Utilities",
@@ -10682,7 +11179,12 @@ function rootOptionGroupLabel(flags) {
   }
   return "General";
 }
-var program = new Command();
+function visibleOptions2(cmd) {
+  return cmd.options.filter((option) => {
+    return !option.hidden;
+  });
+}
+var program = new Command2();
 var argvTokens = process.argv.slice(2);
 var isHelpInvocation = argvTokens.some(
   (token) => token === "help" || token === "--help" || token === "-h"
@@ -10698,6 +11200,16 @@ var findCommandByPath = (root, path) => {
   }
   return current;
 };
+var commandPathIncludes = (command, names) => {
+  let current = command;
+  while (current) {
+    if (names.has(current.name())) {
+      return true;
+    }
+    current = current.parent ?? null;
+  }
+  return false;
+};
 var cachedAvailableUpdate;
 var updateShownDuringInteractiveStartup = false;
 function getAvailableUpdateOnce() {
@@ -10718,7 +11230,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.15.0", "-v, --version", "display CLI version").option("--api-key <key>", "Alchemy API key (env: ALCHEMY_API_KEY)").option(
+).version("0.16.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(
@@ -10756,7 +11268,7 @@ program.name("alchemy").description(
           required: a.required
         }));
       }
-      const opts = cmd.options;
+      const opts = visibleOptions2(cmd);
       if (opts.length > 0) {
         schema.options = opts.map((o) => ({
           flags: o.flags,
@@ -10891,11 +11403,11 @@ ${styledLine}`;
     reveal: Boolean(opts.reveal),
     timeout: opts.timeout
   });
-  const cmdName = actionCommand.name();
-  const skipAppPrompt = [
+  const skipAppPrompt = /* @__PURE__ */ new Set([
     "auth",
     "config",
     "help",
+    "usage",
     "version",
     "completions",
     "agent-prompt",
@@ -10903,13 +11415,13 @@ ${styledLine}`;
     "install",
     "update-check",
     "wallet"
-  ];
-  if (!skipAppPrompt.includes(cmdName) && isInteractiveAllowed(program) && !opts.apiKey && !process.env.ALCHEMY_API_KEY) {
-    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-IRTGQL4A.js");
+  ]);
+  if (!commandPathIncludes(actionCommand, skipAppPrompt) && isInteractiveAllowed(program) && !opts.apiKey && !process.env.ALCHEMY_API_KEY) {
+    const { resolveAuthToken: resolveAuthToken2 } = await import("./resolve-B64J4LR6.js");
     const authToken = resolveAuthToken2(cfg);
     const hasApiKey = Boolean(cfg.api_key?.trim() || cfg.app?.apiKey);
     if (authToken && !hasApiKey) {
-      const { selectAppAfterAuth } = await import("./auth-ZBEPAFEP.js");
+      const { selectAppAfterAuth } = await import("./auth-JHVDOG26.js");
       console.log("");
       console.log(`  No app selected. Please select an app to continue.`);
       await selectAppAfterAuth(authToken);
@@ -10944,7 +11456,7 @@ ${styledLine}`;
   if (isInteractiveAllowed(program)) {
     let latestForInteractiveStartup = null;
     if (shouldRunOnboarding(program, cfg)) {
-      const { runOnboarding } = await import("./onboarding-L2FTZRYN.js");
+      const { runOnboarding } = await import("./onboarding-47TK4HNM.js");
       const latest = getAvailableUpdateOnce();
       const completed = await runOnboarding(program, latest);
       updateShownDuringInteractiveStartup = Boolean(latest);
@@ -10958,7 +11470,7 @@ ${styledLine}`;
         latestForInteractiveStartup
       );
     }
-    const { startREPL } = await import("./interactive-3ACOLHPG.js");
+    const { startREPL } = await import("./interactive-PQGRT27R.js");
     program.exitOverride();
     program.configureOutput({
       writeErr: () => {
@@ -10975,6 +11487,7 @@ registerXchain(program);
 registerWallets(program);
 registerGasManager(program);
 registerApps(program);
+registerUsage(program);
 registerWebhooks(program);
 registerAuth(program);
 registerConfig(program);

package/dist/{interactive-3ACOLHPG.js → interactive-PQGRT27R.js}

@@ -2,14 +2,14 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getSetupMethod
-} from "./chunk-RQDWIB62.js";
+} from "./chunk-Q2VRERYE.js";
 import "./chunk-EJB4WDTU.js";
 import {
   getRPCNetworkIds
-} from "./chunk-CXR7CCJ7.js";
+} from "./chunk-FFQ7XKW7.js";
 import {
   getUpdateNoticeLines
-} from "./chunk-UL5ZSWTE.js";
+} from "./chunk-N422J6U3.js";
 import {
   bold,
   brand,
@@ -17,7 +17,7 @@ import {
   dim,
   green,
   setBrandedHelpSuppressed
-} from "./chunk-OIRERSZT.js";
+} from "./chunk-GJL52AFY.js";
 import {
   configDir,
   load

package/dist/{onboarding-L2FTZRYN.js → onboarding-47TK4HNM.js}

@@ -2,7 +2,7 @@
 if(process.argv.includes("--no-color"))process.env.NO_COLOR="1";
 import {
   getUpdateNoticeLines
-} from "./chunk-UL5ZSWTE.js";
+} from "./chunk-N422J6U3.js";
 import {
   bold,
   brand,
@@ -10,7 +10,7 @@ import {
   dim,
   green,
   promptText
-} from "./chunk-OIRERSZT.js";
+} from "./chunk-GJL52AFY.js";
 import {
   load,
   save
@@ -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-ZBEPAFEP.js");
+    const { selectAppAfterAuth } = await import("./auth-JHVDOG26.js");
     await selectAppAfterAuth(result.token);
     return true;
   } catch (err) {

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

@@ -5,9 +5,9 @@ import {
   errNotLoggedInForPolicyLookup,
   errSponsorshipNeedsPolicy,
   selectOrCreatePolicy
-} from "./chunk-M7HFRKW6.js";
-import "./chunk-CXR7CCJ7.js";
-import "./chunk-OIRERSZT.js";
+} from "./chunk-HPRJEGSP.js";
+import "./chunk-FFQ7XKW7.js";
+import "./chunk-GJL52AFY.js";
 import "./chunk-PISUI34T.js";
 import "./chunk-CFIDLPKB.js";
 export {

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

@@ -26,7 +26,7 @@ import {
   resolveWalletSession,
   resolveX402,
   resolveX402Client
-} from "./chunk-CXR7CCJ7.js";
+} from "./chunk-FFQ7XKW7.js";
 import "./chunk-PISUI34T.js";
 import "./chunk-CFIDLPKB.js";
 export {

package/package.json

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