feat(dashboard): rich terminal chart rendering for dashboard view

Add a full chart rendering engine for `sentry dashboard view` that
transforms widget data into rich terminal visualizations.

- **Big numbers**: 4-tier auto-scaling ASCII art fonts (7×7 → 5×5 →
  3×3 → single-line) with vertical centering
- **Time-series bars**: Fractional block characters (▁▂▃▄▅▆▇█) for
  smooth bar tops with Y-axis ticks and time-axis labels
- **Stacked multi-series bars**: Distinct colors per series with
  a color-keyed legend (■ markers)
- **Categorical bars**: Direct labels for short names, letter-keyed
  legend (A:label B:label…) for long ones
- **Horizontal bars**: Filled + background bar with value labels
- **Sparklines**: Compact inline graphs for small widgets
- **Tables**: Markdown table rendering

- Framebuffer grid compositing matching Sentry's widget layout
- Dynamic terminal width (re-reads on each render cycle)
- Y-axis with compact tick labels (formatTickLabel: 321K, 1.5M)
- Time-axis with ┬ tick marks and auto-formatted date labels
- Rounded Unicode borders with embedded widget titles
- Multi-series aggregation for grouped time-series data

- Widget data querying with environment/project filters
- Zod schemas for dashboard API response validation
- Downsample values and timestamps for terminal-width fitting

Author: BYK

AGENTS.md

@@ -44,6 +44,8 @@ View a dashboard
 **Flags:**
 - `-w, --web - Open in browser`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
+- `-r, --refresh <value> - Auto-refresh interval in seconds (default: 60, min: 10)`
+- `-t, --period <value> - Time period override (e.g., "24h", "7d", "14d")`
 
 **Examples:**
 

plugins/sentry-cli/skills/sentry-cli/references/dashboards.md

@@ -1,54 +1,148 @@
 /**
  * sentry dashboard view
  *
- * View details of a specific dashboard.
+ * View a dashboard with rendered widget data (sparklines, tables, big numbers).
+ * Supports --refresh for auto-refreshing live display.
  */
 
 import type { SentryContext } from "../../context.js";
-import { getDashboard } from "../../lib/api-client.js";
+import { getDashboard, queryAllWidgets } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
-import { formatDashboardView } from "../../lib/formatters/human.js";
+import type { DashboardViewData } from "../../lib/formatters/dashboard.js";
+import { createDashboardViewRenderer } from "../../lib/formatters/dashboard.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
+import { isPlainOutput } from "../../lib/formatters/plain-detect.js";
 import {
   applyFreshFlag,
   FRESH_ALIASES,
   FRESH_FLAG,
 } from "../../lib/list-command.js";
+import { logger } from "../../lib/logger.js";
 import { withProgress } from "../../lib/polling.js";
+import { resolveOrgRegion } from "../../lib/region.js";
 import { buildDashboardUrl } from "../../lib/sentry-urls.js";
-import type { DashboardDetail } from "../../types/dashboard.js";
+import type {
+  DashboardWidget,
+  WidgetDataResult,
+} from "../../types/dashboard.js";
 import {
   parseDashboardPositionalArgs,
   resolveDashboardId,
   resolveOrgFromTarget,
 } from "./resolve.js";
 
+/** Default auto-refresh interval in seconds */
+const DEFAULT_REFRESH_INTERVAL = 60;
+
+/** Minimum auto-refresh interval in seconds (avoid rate limiting) */
+const MIN_REFRESH_INTERVAL = 10;
+
 type ViewFlags = {
   readonly web: boolean;
   readonly fresh: boolean;
+  readonly refresh?: number;
+  readonly period?: string;
   readonly json: boolean;
   readonly fields?: string[];
 };
 
-type ViewResult = DashboardDetail & { url: string };
+/**
+ * Parse --refresh flag value.
+ * Supports: -r (empty string → 60s default), -r 30 (explicit interval in seconds)
+ */
+function parseRefresh(value: string): number {
+  if (value === "") {
+    return DEFAULT_REFRESH_INTERVAL;
+  }
+  const num = Number.parseInt(value, 10);
+  if (Number.isNaN(num) || num < MIN_REFRESH_INTERVAL) {
+    throw new Error(
+      `--refresh interval must be at least ${MIN_REFRESH_INTERVAL} seconds`
+    );
+  }
+  return num;
+}
+
+/**
+ * Sleep that resolves early when an AbortSignal fires.
+ * Resolves (not rejects) on abort for clean generator shutdown.
+ */
+function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Build the DashboardViewData from a dashboard and its widget query results.
+ */
+function buildViewData(
+  dashboard: {
+    id: string;
+    title: string;
+    dateCreated?: string;
+    environment?: string[];
+  },
+  widgetResults: Map<number, WidgetDataResult>,
+  widgets: DashboardWidget[],
+  opts: { period: string; url: string }
+): DashboardViewData {
+  return {
+    id: dashboard.id,
+    title: dashboard.title,
+    period: opts.period,
+    fetchedAt: new Date().toISOString(),
+    url: opts.url,
+    dateCreated: dashboard.dateCreated,
+    environment: dashboard.environment,
+    widgets: widgets.map((w, i) => ({
+      title: w.title,
+      displayType: w.displayType,
+      widgetType: w.widgetType,
+      layout: w.layout,
+      queries: w.queries,
+      data: widgetResults.get(i) ?? {
+        type: "error" as const,
+        message: "No data returned",
+      },
+    })),
+  };
+}
 
 export const viewCommand = buildCommand({
   docs: {
     brief: "View a dashboard",
     fullDescription:
-      "View details of a specific Sentry dashboard.\n\n" +
+      "View a Sentry dashboard with rendered widget data.\n\n" +
+      "Fetches actual data for each widget and displays sparkline charts,\n" +
+      "tables, and big numbers in the terminal.\n\n" +
       "The dashboard can be specified by numeric ID or title.\n\n" +
       "Examples:\n" +
       "  sentry dashboard view 12345\n" +
       "  sentry dashboard view 'My Dashboard'\n" +
       "  sentry dashboard view my-org/ 12345\n" +
       "  sentry dashboard view 12345 --json\n" +
+      "  sentry dashboard view 12345 --period 7d\n" +
+      "  sentry dashboard view 12345 -r\n" +
+      "  sentry dashboard view 12345 -r 30\n" +
       "  sentry dashboard view 12345 --web",
   },
   output: {
-    human: formatDashboardView,
+    human: createDashboardViewRenderer,
   },
   parameters: {
     positional: {
@@ -65,8 +159,21 @@ export const viewCommand = buildCommand({
         default: false,
       },
       fresh: FRESH_FLAG,
+      refresh: {
+        kind: "parsed",
+        parse: parseRefresh,
+        brief: "Auto-refresh interval in seconds (default: 60, min: 10)",
+        optional: true,
+        inferEmpty: true,
+      },
+      period: {
+        kind: "parsed",
+        parse: String,
+        brief: 'Time period override (e.g., "24h", "7d", "14d")',
+        optional: true,
+      },
     },
-    aliases: { ...FRESH_ALIASES, w: "web" },
+    aliases: { ...FRESH_ALIASES, w: "web", r: "refresh", t: "period" },
   },
   async *func(this: SentryContext, flags: ViewFlags, ...args: string[]) {
     applyFreshFlag(flags);
@@ -80,20 +187,76 @@ export const viewCommand = buildCommand({
       "sentry dashboard view <org>/ <id>"
     );
     const dashboardId = await resolveDashboardId(orgSlug, dashboardRef);
-
     const url = buildDashboardUrl(orgSlug, dashboardId);
 
     if (flags.web) {
       await openInBrowser(url, "dashboard");
       return;
     }
 
+    // Fetch the dashboard definition (widget structure)
     const dashboard = await withProgress(
       { message: "Fetching dashboard...", json: flags.json },
       () => getDashboard(orgSlug, dashboardId)
     );
 
-    yield new CommandOutput({ ...dashboard, url } as ViewResult);
+    const regionUrl = await resolveOrgRegion(orgSlug);
+    const period = flags.period ?? dashboard.period ?? "24h";
+    const widgets = dashboard.widgets ?? [];
+
+    if (flags.refresh !== undefined) {
+      // ── Refresh mode: poll and re-render ──
+      const interval = flags.refresh;
+      if (!flags.json) {
+        logger.info(
+          `Auto-refreshing dashboard every ${interval}s. Press Ctrl+C to stop.`
+        );
+      }
+
+      const controller = new AbortController();
+      const stop = () => controller.abort();
+      process.once("SIGINT", stop);
+
+      // Use in-place refresh on interactive terminals (ANSI clear)
+      const canClear = !(isPlainOutput() || flags.json);
+      let isFirstRender = true;
+
+      try {
+        while (!controller.signal.aborted) {
+          const widgetData = await queryAllWidgets(
+            regionUrl,
+            orgSlug,
+            dashboard,
+            { period }
+          );
+
+          // Clear screen for in-place refresh (skip for first render and piped output)
+          if (!isFirstRender && canClear) {
+            this.stdout.write("\x1b[H\x1b[J");
+          }
+          isFirstRender = false;
+
+          yield new CommandOutput(
+            buildViewData(dashboard, widgetData, widgets, { period, url })
+          );
+
+          await abortableSleep(interval * 1000, controller.signal);
+        }
+      } finally {
+        process.removeListener("SIGINT", stop);
+      }
+      return;
+    }
+
+    // ── Single fetch mode ──
+    const widgetData = await withProgress(
+      { message: "Querying widget data...", json: flags.json },
+      () => queryAllWidgets(regionUrl, orgSlug, dashboard, { period })
+    );
+
+    yield new CommandOutput(
+      buildViewData(dashboard, widgetData, widgets, { period, url })
+    );
     return { hint: `Dashboard: ${url}` };
   },
 });

src/commands/dashboard/view.ts

@@ -23,7 +23,10 @@ export {
   createDashboard,
   getDashboard,
   listDashboards,
+  queryAllWidgets,
+  queryWidgetData,
   updateDashboard,
+  type WidgetQueryOptions,
 } from "./api/dashboards.js";
 export {
   findEventAcrossOrgs,