feat(dashboard): add dashboard list, view, and create commands (#406)

## Summary
- Add `sentry dashboard list` — list dashboards with `--web` and
`--json` support
- Add `sentry dashboard view` — view dashboard detail by numeric ID or
title (case-insensitive match)
- Add `sentry dashboard create` — create dashboards with optional inline
`--widget-*` flags for quick widget creation
- Add dashboard API client functions (`listDashboards`, `getDashboard`,
`createDashboard`, `updateDashboard`)
- Add Zod-validated aggregate function and search filter constants for
spans/discover datasets
- Add `parseAggregate()` / `parseSortExpression()` shorthand for
CLI-friendly aggregate syntax (e.g. `count` → `count()`,
`p95:span.duration` → `p95(span.duration)`)
- Add auto-layout engine that packs widgets into the 6-column grid

Split from #401. Widget commands (add/edit/delete) follow in a stacked
PR.

## Test plan
- [x] `bun run typecheck` — no new type errors
- [x] `bun run lint` — passes
- [x] `bun test test/types/dashboard.test.ts` — 53 tests pass (enum
constants, schema validation, parseAggregate, parseSortExpression,
prepareWidgetQueries)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Burak Yigit Kaya <byk@sentry.io>

Author: 3 people

AGENTS.md

@@ -505,6 +505,39 @@ Update the Sentry CLI to the latest version
 - `--json - Output as JSON`
 - `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
 
+### Dashboard
+
+Manage Sentry dashboards
+
+#### `sentry dashboard list <org/project>`
+
+List dashboards
+
+**Flags:**
+- `-w, --web - Open in browser`
+- `-n, --limit <value> - Maximum number of dashboards to list - (default: "30")`
+- `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
+
+#### `sentry dashboard view <args...>`
+
+View a dashboard
+
+**Flags:**
+- `-w, --web - Open in browser`
+- `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
+
+#### `sentry dashboard create <args...>`
+
+Create a dashboard
+
+**Flags:**
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
+
 ### Repo
 
 Work with Sentry repositories

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -11,6 +11,8 @@ import { apiCommand } from "./commands/api.js";
 import { authRoute } from "./commands/auth/index.js";
 import { whoamiCommand } from "./commands/auth/whoami.js";
 import { cliRoute } from "./commands/cli/index.js";
+import { dashboardRoute } from "./commands/dashboard/index.js";
+import { listCommand as dashboardListCommand } from "./commands/dashboard/list.js";
 import { eventRoute } from "./commands/event/index.js";
 import { helpCommand } from "./commands/help.js";
 import { initCommand } from "./commands/init.js";
@@ -47,6 +49,7 @@ import { error as errorColor, warning } from "./lib/formatters/colors.js";
  * Used to suggest the correct command when users type e.g. `sentry projects view cli`.
  */
 const PLURAL_TO_SINGULAR: Record<string, string> = {
+  dashboards: "dashboard",
   issues: "issue",
   orgs: "org",
   projects: "project",
@@ -64,6 +67,7 @@ export const routes = buildRouteMap({
     help: helpCommand,
     auth: authRoute,
     cli: cliRoute,
+    dashboard: dashboardRoute,
     org: orgRoute,
     project: projectRoute,
     repo: repoRoute,
@@ -77,6 +81,7 @@ export const routes = buildRouteMap({
     init: initCommand,
     api: apiCommand,
     schema: schemaCommand,
+    dashboards: dashboardListCommand,
     issues: issueListCommand,
     orgs: orgListCommand,
     projects: projectListCommand,
@@ -95,6 +100,7 @@ export const routes = buildRouteMap({
       "sentry is a command-line interface for interacting with Sentry. " +
       "It provides commands for authentication, viewing issues, and making API calls.",
     hideRoute: {
+      dashboards: true,
       issues: true,
       orgs: true,
       projects: true,

src/app.ts

@@ -0,0 +1,171 @@
+/**
+ * sentry dashboard create
+ *
+ * Create a new dashboard in a Sentry organization.
+ */
+
+import type { SentryContext } from "../../context.js";
+import { createDashboard, getProject } from "../../lib/api-client.js";
+import {
+  type ParsedOrgProject,
+  parseOrgProjectArg,
+} from "../../lib/arg-parsing.js";
+import { buildCommand } from "../../lib/command.js";
+import { ContextError, ValidationError } from "../../lib/errors.js";
+import { formatDashboardCreated } from "../../lib/formatters/human.js";
+import { CommandOutput } from "../../lib/formatters/output.js";
+import {
+  fetchProjectId,
+  resolveAllTargets,
+  resolveOrg,
+  resolveProjectBySlug,
+  toNumericId,
+} from "../../lib/resolve-target.js";
+import { buildDashboardUrl } from "../../lib/sentry-urls.js";
+import type { DashboardDetail } from "../../types/dashboard.js";
+
+type CreateFlags = {
+  readonly json: boolean;
+  readonly fields?: string[];
+};
+
+type CreateResult = DashboardDetail & { url: string };
+
+/**
+ * Parse array positional args for `dashboard create`.
+ *
+ * Handles:
+ * - `<title>` — title only (auto-detect org/project)
+ * - `<target> <title>` — explicit target + title
+ */
+function parsePositionalArgs(args: string[]): {
+  title: string;
+  targetArg: string | undefined;
+} {
+  if (args.length === 0) {
+    throw new ValidationError("Dashboard title is required.", "title");
+  }
+  if (args.length === 1) {
+    return { title: args[0] as string, targetArg: undefined };
+  }
+  // Two args: first is target, second is title
+  return { title: args[1] as string, targetArg: args[0] as string };
+}
+
+/** Result of resolving org + project IDs from the parsed target */
+type ResolvedDashboardTarget = {
+  orgSlug: string;
+  projectIds: number[];
+};
+
+/** Enrich targets that lack a projectId by calling the project API */
+async function enrichTargetProjectIds(
+  targets: { org: string; project: string; projectId?: number }[]
+): Promise<number[]> {
+  const enriched = await Promise.all(
+    targets.map(async (t) => {
+      if (t.projectId !== undefined) {
+        return t.projectId;
+      }
+      try {
+        const info = await getProject(t.org, t.project);
+        return toNumericId(info.id);
+      } catch {
+        return;
+      }
+    })
+  );
+  return enriched.filter((id): id is number => id !== undefined);
+}
+
+/** Resolve org and project IDs from the parsed target argument */
+async function resolveDashboardTarget(
+  parsed: ParsedOrgProject,
+  cwd: string
+): Promise<ResolvedDashboardTarget> {
+  switch (parsed.type) {
+    case "explicit": {
+      const pid = await fetchProjectId(parsed.org, parsed.project);
+      return {
+        orgSlug: parsed.org,
+        projectIds: pid !== undefined ? [pid] : [],
+      };
+    }
+    case "org-all":
+      return { orgSlug: parsed.org, projectIds: [] };
+
+    case "project-search": {
+      const found = await resolveProjectBySlug(
+        parsed.projectSlug,
+        "sentry dashboard create <org>/<project> <title>"
+      );
+      const pid = await fetchProjectId(found.org, found.project);
+      return {
+        orgSlug: found.org,
+        projectIds: pid !== undefined ? [pid] : [],
+      };
+    }
+    case "auto-detect": {
+      const result = await resolveAllTargets({ cwd });
+      if (result.targets.length === 0) {
+        const resolved = await resolveOrg({ cwd });
+        if (!resolved) {
+          throw new ContextError(
+            "Organization",
+            "sentry dashboard create <org>/ <title>"
+          );
+        }
+        return { orgSlug: resolved.org, projectIds: [] };
+      }
+      const orgSlug = (result.targets[0] as (typeof result.targets)[0]).org;
+      const projectIds = await enrichTargetProjectIds(result.targets);
+      return { orgSlug, projectIds };
+    }
+    default: {
+      const _exhaustive: never = parsed;
+      throw new Error(
+        `Unexpected parsed type: ${(_exhaustive as { type: string }).type}`
+      );
+    }
+  }
+}
+
+export const createCommand = buildCommand({
+  docs: {
+    brief: "Create a dashboard",
+    fullDescription:
+      "Create a new Sentry dashboard.\n\n" +
+      "Examples:\n" +
+      "  sentry dashboard create 'My Dashboard'\n" +
+      "  sentry dashboard create my-org/ 'My Dashboard'\n" +
+      "  sentry dashboard create my-org/my-project 'My Dashboard'",
+  },
+  output: {
+    human: formatDashboardCreated,
+  },
+  parameters: {
+    positional: {
+      kind: "array",
+      parameter: {
+        brief: "[<org/project>] <title>",
+        parse: String,
+      },
+    },
+    flags: {},
+  },
+  async *func(this: SentryContext, _flags: CreateFlags, ...args: string[]) {
+    const { cwd } = this;
+
+    const { title, targetArg } = parsePositionalArgs(args);
+    const parsed = parseOrgProjectArg(targetArg);
+    const { orgSlug, projectIds } = await resolveDashboardTarget(parsed, cwd);
+
+    const dashboard = await createDashboard(orgSlug, {
+      title,
+      projects: projectIds.length > 0 ? projectIds : undefined,
+    });
+    const url = buildDashboardUrl(orgSlug, dashboard.id);
+
+    yield new CommandOutput({ ...dashboard, url } as CreateResult);
+  },
+});

src/commands/dashboard/create.ts

@@ -0,0 +1,22 @@
+import { buildRouteMap } from "@stricli/core";
+import { createCommand } from "./create.js";
+import { listCommand } from "./list.js";
+import { viewCommand } from "./view.js";
+
+export const dashboardRoute = buildRouteMap({
+  routes: {
+    list: listCommand,
+    view: viewCommand,
+    create: createCommand,
+  },
+  docs: {
+    brief: "Manage Sentry dashboards",
+    fullDescription:
+      "View and manage dashboards in your Sentry organization.\n\n" +
+      "Commands:\n" +
+      "  list     List dashboards\n" +
+      "  view     View a dashboard\n" +
+      "  create   Create a dashboard",
+    hideRoute: {},
+  },
+});