@k2b/cloud 0.6.0-rc.0

package/src/cli/admin/logs.ts

@@ -0,0 +1,324 @@
+/**
+ * Structured application logs — listing, aggregation, and the correlation
+ * helpers (`problems`, `explain`) that turn one entry into context.
+ */
+import { arg, type CloudCliContext, type CloudCliTableColumn, command, confirmFlag, flag, paginationFlags } from "../index";
+import type { GatewayHealth } from "./gateway";
+import {
+  apiGet,
+  type Pagination,
+  pageQuery,
+  parseLookbackHours,
+  printJsonOrTable,
+  queryString,
+  safeCollect,
+  sleep,
+  sortByTimeDesc,
+  truncate,
+} from "./shared";
+import type { TelemetryEvent } from "./telemetry";
+
+export type LogEntry = {
+  id: string;
+  level: "debug" | "info" | "warn" | "error";
+  source: string;
+  message: string;
+  metadata: Record<string, unknown> | null;
+  createdAt: string;
+};
+
+export type LogSummary = {
+  total: number;
+  errors24h: number;
+  warnings24h: number;
+  total24h: number;
+  sources: number;
+  lastErrorAt: string | null;
+};
+
+export type LogStatsResponse = {
+  groupBy: "source" | "level";
+  items: { key: string; count: number }[];
+};
+
+export const PG_BIGINT_MAX = 9_223_372_036_854_775_807n;
+
+export const parseLogId = (value: string): string => {
+  if (!/^[1-9]\d*$/.test(value)) throw new Error("Log id must be a positive integer.");
+  if (BigInt(value) > PG_BIGINT_MAX) throw new Error("Log id must fit into a Postgres BIGINT.");
+  return value;
+};
+
+export const logRows = (entries: LogEntry[], messageLength = 120) =>
+  entries.map((entry) => ({
+    time: entry.createdAt,
+    level: entry.level,
+    source: entry.source,
+    message: truncate(entry.message, messageLength),
+    metadata: entry.metadata ? "yes" : "",
+    id: entry.id,
+  }));
+
+export const logColumns = [
+  { key: "time" },
+  { key: "level" },
+  { key: "source" },
+  { key: "message" },
+  { key: "metadata" },
+  { key: "id" },
+] satisfies CloudCliTableColumn<ReturnType<typeof logRows>[number]>[];
+
+export const getLogs = async (
+  ctx: CloudCliContext,
+  params: {
+    search?: string;
+    source?: string;
+    level?: "debug" | "info" | "warn" | "error";
+    sinceHours?: number;
+    page?: number;
+    perPage?: number;
+  },
+): Promise<{ entries: LogEntry[]; pagination: Pagination }> =>
+  apiGet(
+    ctx,
+    `/api/logging${queryString({
+      search: params.search,
+      source: params.source,
+      level: params.level,
+      since_hours: params.sinceHours,
+      ...pageQuery(params),
+    })}`,
+  );
+
+export const trimLogMessages = <T extends { entries: LogEntry[] }>(result: T, messageLength: number): T => ({
+  ...result,
+  entries: result.entries.map((entry) => ({ ...entry, message: truncate(entry.message, messageLength) })),
+});
+
+export const logCommands = [
+  command("logs list", {
+    summary: "List log entries with source, level, and free-text filters",
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Free-text log search" }),
+      source: flag.string({ description: "Log source filter" }),
+      level: flag.enum(["debug", "info", "warn", "error"], { description: "Log level filter" }),
+      since: flag.string({ description: "Lookback window like 30m, 6h, or 7d" }),
+      messageLength: flag.int({ name: "message-length", default: 140, min: 40, max: 1000, description: "Table message preview length" }),
+      ...paginationFlags({ defaultPerPage: 50, maxPerPage: 100 }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await getLogs(ctx, { ...flags, sinceHours: flags.since ? parseLookbackHours(flags.since) : undefined });
+      printJsonOrTable(ctx, result, logRows(result.entries, flags.messageLength), logColumns);
+    },
+  }),
+  command("logs summary", {
+    summary: "Show log volume and recent error summary",
+    run: async ({ ctx }) => {
+      const result = await apiGet<LogSummary>(ctx, "/api/logging/summary");
+      printJsonOrTable(
+        ctx,
+        result,
+        [result],
+        [{ key: "total" }, { key: "total24h" }, { key: "errors24h" }, { key: "warnings24h" }, { key: "sources" }, { key: "lastErrorAt" }],
+      );
+    },
+  }),
+  command("logs stats", {
+    summary: "Group log volume by source or level",
+    flags: {
+      groupBy: flag.enum(["source", "level"], { name: "group-by", default: "source", description: "Stats dimension" }),
+      since: flag.string({ default: "24h", description: "Lookback window like 30m, 6h, or 7d" }),
+      limit: flag.int({ default: 50, min: 1, max: 200, description: "Maximum groups" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await apiGet<LogStatsResponse>(
+        ctx,
+        `/api/logging/stats${queryString({
+          group_by: flags.groupBy,
+          since_hours: parseLookbackHours(flags.since),
+          limit: flags.limit,
+        })}`,
+      );
+      printJsonOrTable(ctx, result, result.items, [
+        { key: "key", label: flags.groupBy === "level" ? "level" : "source" },
+        { key: "count" },
+      ]);
+    },
+  }),
+  command("logs errors", {
+    summary: "List recent error logs for incident debugging",
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Free-text log search" }),
+      source: flag.string({ description: "Log source filter" }),
+      since: flag.string({ default: "24h", description: "Lookback window like 30m, 6h, or 7d" }),
+      messageLength: flag.int({ name: "message-length", default: 180, min: 40, max: 1000, description: "Table message preview length" }),
+      ...paginationFlags({ defaultPerPage: 25, maxPerPage: 100 }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await getLogs(ctx, { ...flags, level: "error", sinceHours: parseLookbackHours(flags.since) });
+      printJsonOrTable(ctx, result, logRows(result.entries, flags.messageLength), logColumns);
+    },
+  }),
+  command("logs problems", {
+    summary: "List recent warn and error logs together",
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Free-text log search" }),
+      source: flag.string({ description: "Log source filter" }),
+      since: flag.string({ default: "24h", description: "Lookback window like 30m, 6h, or 7d" }),
+      limit: flag.int({ default: 50, min: 1, max: 100, description: "Maximum combined rows" }),
+      messageLength: flag.int({ name: "message-length", default: 160, min: 40, max: 1000, description: "Table message preview length" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const perPage = flags.limit ?? 50;
+      const sinceHours = parseLookbackHours(flags.since);
+      const [errors, warnings] = await Promise.all([
+        getLogs(ctx, { search: flags.search, source: flags.source, level: "error", sinceHours, perPage }),
+        getLogs(ctx, { search: flags.search, source: flags.source, level: "warn", sinceHours, perPage }),
+      ]);
+      const entries = sortByTimeDesc([...errors.entries, ...warnings.entries]).slice(0, perPage);
+      const result = { entries, totals: { errors: errors.pagination.total, warnings: warnings.pagination.total } };
+      printJsonOrTable(ctx, result, logRows(entries, flags.messageLength), logColumns);
+    },
+  }),
+  command("logs show", {
+    summary: "Show one log entry with full message and metadata",
+    args: { id: arg.required({ valueLabel: "id" }) },
+    run: async ({ ctx, args }) => {
+      const id = parseLogId(args.id);
+      const result = await apiGet<LogEntry>(ctx, `/api/logging/${id}`);
+      if (ctx.options.output === "json") {
+        ctx.json(result);
+        return;
+      }
+      const metadata = result.metadata ? `\nmetadata:\n${JSON.stringify(result.metadata, null, 2)}` : "";
+      ctx.print(`[${result.createdAt}] ${result.level} ${result.source} #${result.id}\n${result.message}${metadata}`);
+    },
+  }),
+  command("logs explain", {
+    summary: "Collect one log entry with nearby diagnostic context",
+    args: { id: arg.required({ valueLabel: "id" }) },
+    flags: {
+      since: flag.string({ default: "24h", description: "Context lookback window like 30m, 6h, or 7d" }),
+      limit: flag.int({ default: 20, min: 1, max: 50, description: "Context rows per section" }),
+      messageLength: flag.int({ name: "message-length", default: 500, min: 40, max: 5000, description: "Context log message length" }),
+    },
+    run: async ({ ctx, args, flags }) => {
+      const id = parseLogId(args.id);
+      const log = await apiGet<LogEntry>(ctx, `/api/logging/${id}`);
+      const sinceHours = parseLookbackHours(flags.since);
+      const limit = flags.limit ?? 20;
+      const [sameSource, recentProblems, telemetryErrors, appHealth] = await Promise.all([
+        safeCollect("same source logs", () => getLogs(ctx, { source: log.source, sinceHours, perPage: limit })),
+        safeCollect("recent warn/error logs", async () => {
+          const [errors, warnings] = await Promise.all([
+            getLogs(ctx, { level: "error", sinceHours, perPage: limit }),
+            getLogs(ctx, { level: "warn", sinceHours, perPage: limit }),
+          ]);
+          return sortByTimeDesc([...errors.entries, ...warnings.entries]).slice(0, limit);
+        }),
+        safeCollect("telemetry errors", () =>
+          apiGet<{ items: TelemetryEvent[]; total: number }>(
+            ctx,
+            `/api/gateway/telemetry/events${queryString({ errors: "1", hours: sinceHours, page: 1, per_page: limit })}`,
+          ),
+        ),
+        safeCollect("app health", async () => {
+          const health = await apiGet<GatewayHealth>(ctx, "/api/gateway/health");
+          return health.apps.find((app) => app.id === log.source || app.name === log.source) ?? null;
+        }),
+      ]);
+      const trimEntry = (entry: LogEntry) => ({ ...entry, message: truncate(entry.message, flags.messageLength ?? 500) });
+      const bundle = {
+        log,
+        lookbackHours: sinceHours,
+        sameSource:
+          sameSource.ok && flags.messageLength
+            ? { ...sameSource, data: trimLogMessages(sameSource.data, flags.messageLength) }
+            : sameSource,
+        recentProblems: recentProblems.ok ? { ...recentProblems, data: recentProblems.data.map(trimEntry) } : recentProblems,
+        telemetryErrors,
+        appHealth,
+      };
+      if (ctx.options.output === "json") {
+        ctx.json(bundle);
+        return;
+      }
+      const lines = [
+        `[${log.createdAt}] ${log.level} ${log.source} #${log.id}`,
+        log.message,
+        "",
+        `same-source logs: ${sameSource.ok ? sameSource.data.entries.length : `unavailable (${sameSource.error})`}`,
+        `recent problems: ${recentProblems.ok ? recentProblems.data.length : `unavailable (${recentProblems.error})`}`,
+        `telemetry errors: ${telemetryErrors.ok ? telemetryErrors.data.items.length : `unavailable (${telemetryErrors.error})`}`,
+        `app health: ${appHealth.ok ? (appHealth.data ? `${appHealth.data.status} (${appHealth.data.id})` : "no matching app") : `unavailable (${appHealth.error})`}`,
+      ];
+      ctx.print(lines.join("\n"));
+    },
+  }),
+  command("logs tail", {
+    summary: "Show latest logs, optionally filtered",
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Free-text log search" }),
+      source: flag.string({ description: "Log source filter" }),
+      level: flag.enum(["debug", "info", "warn", "error"], { description: "Log level filter" }),
+      since: flag.string({ description: "Lookback window like 30m, 6h, or 7d" }),
+      lines: flag.int({ default: 20, min: 1, max: 100, description: "Rows to show" }),
+      follow: flag.boolean({ aliases: ["f"], description: "Poll and print new rows until interrupted" }),
+      interval: flag.int({ default: 2, min: 1, max: 60, description: "Follow poll interval in seconds" }),
+      messageLength: flag.int({ name: "message-length", default: 180, min: 40, max: 1000, description: "Table message preview length" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const load = () =>
+        getLogs(ctx, {
+          search: flags.search,
+          source: flags.source,
+          level: flags.level,
+          sinceHours: flags.since ? parseLookbackHours(flags.since) : undefined,
+          perPage: flags.lines ?? 20,
+        });
+      const result = await load();
+      printJsonOrTable(ctx, result, logRows(result.entries, flags.messageLength), logColumns);
+      if (!flags.follow) return;
+      const seen = new Set(result.entries.map((entry) => entry.id));
+      while (true) {
+        await sleep((flags.interval ?? 2) * 1000);
+        const next = await load();
+        const fresh = next.entries.filter((entry) => !seen.has(entry.id)).reverse();
+        for (const entry of fresh) seen.add(entry.id);
+        if (fresh.length === 0) continue;
+        if (ctx.options.output === "json") {
+          for (const entry of fresh) ctx.json(entry);
+        } else {
+          ctx.table(logRows(fresh, flags.messageLength), logColumns);
+        }
+      }
+    },
+  }),
+  command("logs sources", {
+    summary: "List log sources",
+    run: async ({ ctx }) => {
+      const result = await apiGet<{ sources: string[] }>(ctx, "/api/logging/sources");
+      printJsonOrTable(
+        ctx,
+        result,
+        result.sources.map((source) => ({ source })),
+        [{ key: "source" }],
+      );
+    },
+  }),
+  command("logs cleanup", {
+    summary: "Delete old retained logs",
+    flags: {
+      days: flag.int({ default: 30, min: 1, description: "Delete logs older than this many days" }),
+      yes: confirmFlag("Confirm log cleanup"),
+    },
+    run: async ({ ctx, flags }) => {
+      if (!flags.yes) throw new Error("Refusing to clean logs without --yes.");
+      const result = await ctx.readJson<{ deleted: number }>(
+        await ctx.fetch(`/api/logging/cleanup${queryString({ days: flags.days })}`, { method: "DELETE" }),
+      );
+      if (ctx.options.output === "json") ctx.json(result);
+      else ctx.print(`Deleted ${result.deleted} log entries.`);
+    },
+  }),
+];

package/src/cli/admin/metrics.ts

@@ -0,0 +1,142 @@
+/**
+ * Prometheus metrics snapshot, catalogue, and scrape tokens.
+ */
+import { arg, command, confirmFlag, flag } from "../index";
+import { parseExpiresAt } from "./notifications";
+import { apiGet, apiJson, formatMs, printJsonOrTable, truncate } from "./shared";
+
+export type MetricsToken = {
+  id: string;
+  name: string;
+  tokenPrefix: string;
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  createdAt: string;
+};
+
+export type MetricsCollector = {
+  id: string;
+  name: string;
+  description: string;
+  status: "ok" | "error";
+  series: number;
+  durationMs: number;
+  lastRunAt: string;
+  error: string | null;
+  metricNames: string[];
+};
+
+export const metricsCommands = [
+  command("metrics status", {
+    summary: "Show metric collector status",
+    run: async ({ ctx }) => {
+      const result = await apiGet<{ generatedAt: string; series: number; collectors: MetricsCollector[] }>(
+        ctx,
+        "/api/gateway/metrics/snapshot",
+      );
+      const rows = result.collectors.map((collector) => ({
+        id: collector.id,
+        status: collector.status,
+        series: collector.series,
+        duration: formatMs(collector.durationMs),
+        metrics: collector.metricNames.length,
+        error: truncate(collector.error, 60),
+      }));
+      printJsonOrTable(ctx, result, rows, [
+        { key: "id" },
+        { key: "status" },
+        { key: "series" },
+        { key: "duration" },
+        { key: "metrics" },
+        { key: "error" },
+      ]);
+    },
+  }),
+  command("metrics read", {
+    summary: "Read raw Prometheus metrics",
+    run: async ({ ctx }) => {
+      const response = await ctx.fetch("/metrics");
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`${response.status} ${text.trim() || response.statusText}`);
+      }
+      ctx.print((await response.text()).trimEnd());
+    },
+  }),
+  command("metrics catalogue", {
+    summary: "List exposed metric names by collector",
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Search metric or collector text" }),
+      category: flag.string({ description: "Collector id or name filter" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await apiGet<{ generatedAt: string; series: number; collectors: MetricsCollector[] }>(
+        ctx,
+        "/api/gateway/metrics/snapshot",
+      );
+      const search = flags.search?.toLowerCase();
+      const category = flags.category?.toLowerCase();
+      const rows = result.collectors
+        .filter((collector) => !category || collector.id.toLowerCase() === category || collector.name.toLowerCase() === category)
+        .flatMap((collector) =>
+          collector.metricNames.map((metric) => ({
+            collector: collector.id,
+            name: metric,
+            status: collector.status,
+            series: collector.series,
+            description: truncate(collector.description, 90),
+          })),
+        )
+        .filter((row) => {
+          if (!search) return true;
+          return `${row.collector} ${row.name} ${row.description}`.toLowerCase().includes(search);
+        })
+        .sort((a, b) => a.collector.localeCompare(b.collector) || a.name.localeCompare(b.name));
+      printJsonOrTable(ctx, { generatedAt: result.generatedAt, items: rows }, rows, [
+        { key: "collector" },
+        { key: "name" },
+        { key: "status" },
+        { key: "series" },
+        { key: "description" },
+      ]);
+    },
+  }),
+  command("metrics tokens list", {
+    summary: "List metrics bearer tokens",
+    run: async ({ ctx }) => {
+      const result = await apiGet<{ items: MetricsToken[] }>(ctx, "/api/gateway/metrics/tokens");
+      const rows = result.items.map((token) => ({
+        name: token.name,
+        prefix: token.tokenPrefix,
+        expires: token.expiresAt ?? "never",
+        lastUsed: token.lastUsedAt ?? "never",
+        id: token.id,
+      }));
+      printJsonOrTable(ctx, result, rows, [{ key: "name" }, { key: "prefix" }, { key: "expires" }, { key: "lastUsed" }, { key: "id" }]);
+    },
+  }),
+  command("metrics tokens create", {
+    summary: "Create a metrics bearer token",
+    args: { name: arg.required({ valueLabel: "name" }) },
+    flags: { expiresAt: flag.string({ name: "expires-at", description: "ISO expiry timestamp, never, or null" }) },
+    run: async ({ ctx, args, flags }) => {
+      const result = await apiJson<{ token: string; credential: MetricsToken }>(ctx, "POST", "/api/gateway/metrics/tokens", {
+        name: args.name,
+        expiresAt: parseExpiresAt(flags.expiresAt) ?? null,
+      });
+      if (ctx.options.output === "json") ctx.json(result);
+      else ctx.print(`Token: ${result.token}\nPrefix: ${result.credential.tokenPrefix}\nStore this token now. It cannot be shown again.`);
+    },
+  }),
+  command("metrics tokens revoke", {
+    summary: "Revoke a metrics bearer token",
+    args: { id: arg.required({ valueLabel: "id" }) },
+    flags: { yes: confirmFlag("Confirm metrics token revocation") },
+    run: async ({ ctx, args, flags }) => {
+      if (!flags.yes) throw new Error("Refusing to revoke a metrics token without --yes.");
+      const result = await apiJson<{ message: string }>(ctx, "DELETE", `/api/gateway/metrics/tokens/${encodeURIComponent(args.id)}`);
+      if (ctx.options.output === "json") ctx.json(result);
+      else ctx.print(result.message);
+    },
+  }),
+];

package/src/cli/admin/nats.ts

@@ -0,0 +1,167 @@
+/** Read-only NATS operations; machine output retains snapshot completeness. */
+import { arg, type CloudCliContext, command, flag } from "../index";
+import { apiGet, formatBytes, queryString } from "./shared";
+
+type Replica = { name: string; current: boolean | null; offline: boolean | null; lag: number | null };
+type Cluster = { name: string | null; leader: string | null; replicas: Replica[] };
+type Node = {
+  id: string;
+  name: string;
+  version: string;
+  jetstreamEnabled: boolean;
+  metadataStatus: string;
+  processMemory: number | null;
+  storage: number | null;
+  meta: Cluster | null;
+};
+type Stream = {
+  name: string;
+  kind: string;
+  storage: string;
+  messages: number;
+  bytes: number;
+  consumers: number;
+  replicas: number;
+  deadLetter: boolean;
+  replicationStatus: string | null;
+  hasDeadLetters: boolean;
+  cluster: Cluster | null;
+  sync: { namespace: string; owner: string; kind: string; id: string } | null;
+};
+type Consumer = { name: string; pending: number; ackPending: number; redelivered: number; cluster: Cluster | null };
+export type NatsSnapshot = {
+  sampledAt: string;
+  cluster: { status: string; issue?: string; nodes: Node[] };
+  inventory: {
+    status: string;
+    issue?: string;
+    streams: Stream[];
+    total: number;
+    matchedTotal: number | null;
+    scannedTotal: number;
+    accountTotal: number | null;
+    offset: number;
+    limit: number;
+    nextOffset: number | null;
+    consumers: Consumer[];
+    consumerTotal: number | null;
+    consumerStream: string | null;
+    consumerOffset: number;
+    consumerNextOffset: number | null;
+  };
+};
+const read = (ctx: CloudCliContext, params: Parameters<typeof queryString>[0] = {}) =>
+  apiGet<NatsSnapshot>(ctx, `/api/gateway/nats${queryString(params)}`);
+const machine = (ctx: CloudCliContext, result: NatsSnapshot, section: "nodes" | "streams" | "consumers") => {
+  if (ctx.options.output === "json") {
+    ctx.json(result);
+    return true;
+  }
+  if (ctx.options.output === "jsonl") {
+    const { nodes: _nodes, ...cluster } = result.cluster;
+    const { streams: _streams, consumers: _consumers, ...inventory } = result.inventory;
+    ctx.jsonLine({ type: "snapshot", sampledAt: result.sampledAt, cluster, inventory });
+    for (const item of section === "nodes" ? result.cluster.nodes : result.inventory[section]) ctx.jsonLine({ type: section, ...item });
+    return true;
+  }
+  ctx.print(`Snapshot: ${result.sampledAt}; cluster: ${result.cluster.status}; inventory: ${result.inventory.status}`);
+  if (result.cluster.issue) ctx.error(result.cluster.issue);
+  if (result.inventory.issue) ctx.error(result.inventory.issue);
+  return false;
+};
+export const natsCommands = [
+  command("nats status", {
+    summary: "Inspect NATS nodes and account inventory completeness",
+    run: async ({ ctx }) => {
+      const result = await read(ctx);
+      if (machine(ctx, result, "nodes")) return;
+      ctx.table(
+        result.cluster.nodes.map((node) => ({
+          name: node.name,
+          version: node.version,
+          jetstream: node.jetstreamEnabled ? "enabled" : "disabled",
+          metadataStatus: node.metadataStatus,
+          metadataLeader: node.meta?.leader ?? "unknown",
+          memory: formatBytes(node.processMemory),
+          storage: formatBytes(node.storage),
+        })),
+        [
+          { key: "name" },
+          { key: "version" },
+          { key: "jetstream" },
+          { key: "metadataStatus" },
+          { key: "metadataLeader" },
+          { key: "memory" },
+          { key: "storage" },
+        ],
+      );
+    },
+  }),
+  command("nats streams list", {
+    summary: "Find NATS streams and buckets; filters apply before pagination",
+    flags: {
+      app: flag.string({ description: "Exact Sync owner" }),
+      namespace: flag.string({ description: "Exact Sync namespace" }),
+      resource: flag.string({ description: "Search stream name or Sync resource ID" }),
+      problems: flag.boolean({ description: "Only dead-letter or replication problems" }),
+      offset: flag.int({ min: 0, default: 0, description: "Filtered result offset" }),
+      limit: flag.int({ min: 1, max: 100, default: 50, description: "Rows per page" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await read(ctx, flags);
+      if (machine(ctx, result, "streams")) return;
+      ctx.table(
+        result.inventory.streams.map((stream) => ({
+          name: stream.name,
+          kind: stream.kind,
+          namespace: stream.sync?.namespace ?? "-",
+          app: stream.sync?.owner ?? "-",
+          resource: stream.sync?.id ?? "-",
+          messages: stream.messages,
+          storage: formatBytes(stream.bytes),
+          replicas: stream.replicas,
+          replication: stream.replicationStatus ?? "-",
+          deadLetters: stream.hasDeadLetters ? "yes" : "no",
+          consumers: stream.consumers,
+        })),
+        [
+          { key: "name" },
+          { key: "kind" },
+          { key: "namespace" },
+          { key: "app" },
+          { key: "resource" },
+          { key: "messages" },
+          { key: "storage" },
+          { key: "replicas" },
+          { key: "replication" },
+          { key: "deadLetters" },
+          { key: "consumers" },
+        ],
+      );
+      ctx.print(
+        `Matches: ${result.inventory.matchedTotal ?? `${result.inventory.total}+ (incomplete)`}; next offset: ${result.inventory.nextOffset ?? "none"}`,
+      );
+    },
+  }),
+  command("nats consumers list", {
+    summary: "Inspect consumers and delivery backlog for one NATS stream",
+    args: { stream: arg.required({ valueLabel: "stream" }) },
+    flags: { offset: flag.int({ min: 0, default: 0, description: "Consumer result offset" }) },
+    run: async ({ ctx, args, flags }) => {
+      if (!/^[A-Za-z0-9_-]+$/.test(args.stream)) throw new Error("Invalid NATS stream name.");
+      const result = await read(ctx, { stream: args.stream, consumerOffset: flags.offset });
+      if (machine(ctx, result, "consumers")) return;
+      ctx.table(
+        result.inventory.consumers.map((consumer) => ({
+          name: consumer.name,
+          pending: consumer.pending,
+          ackPending: consumer.ackPending,
+          redelivered: consumer.redelivered,
+          leader: consumer.cluster?.leader ?? "-",
+        })),
+        [{ key: "name" }, { key: "pending" }, { key: "ackPending" }, { key: "redelivered" }, { key: "leader" }],
+      );
+      ctx.print(`Consumers: ${result.inventory.consumerTotal ?? "unknown"}; next offset: ${result.inventory.consumerNextOffset ?? "none"}`);
+    },
+  }),
+];