feat(period): support absolute date ranges in --period flag

docs/src/content/docs/commands/dashboard.md

@@ -43,7 +43,7 @@ View a dashboard
 | `-w, --web` | Open in browser |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-r, --refresh <refresh>` | Auto-refresh interval in seconds (default: 60, min: 10) |
-| `-t, --period <period>` | Time period override (e.g., "24h", "7d", "14d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" |
 
 ### `sentry dashboard create <org/project/title...>`
 

docs/src/content/docs/commands/event.md

@@ -42,7 +42,7 @@ List events for an issue
 | `-n, --limit <limit>` | Number of events (1-1000) (default: "25") |
 | `-q, --query <query>` | Search query (Sentry search syntax) |
 | `--full` | Include full event body (stacktraces) |
-| `-t, --period <period>` | Time period (e.g., "1h", "24h", "7d", "30d") (default: "7d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" (default: "7d") |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-c, --cursor <cursor>` | Navigate pages: "next", "prev", "first" (or raw cursor string) |
 

docs/src/content/docs/commands/issue.md

@@ -24,7 +24,7 @@ List issues in a project
 | `-q, --query <query>` | Search query (Sentry search syntax) |
 | `-n, --limit <limit>` | Maximum number of issues to list (default: "25") |
 | `-s, --sort <sort>` | Sort by: date, new, freq, user (default: "date") |
-| `-t, --period <period>` | Time period for issue activity (e.g. 24h, 14d, 90d) (default: "90d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" (default: "90d") |
 | `-c, --cursor <cursor>` | Pagination cursor (use "next" for next page, "prev" for previous) |
 | `--compact` | Single-line rows for compact output (auto-detects if omitted) |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
@@ -46,7 +46,7 @@ List events for a specific issue
 | `-n, --limit <limit>` | Number of events (1-1000) (default: "25") |
 | `-q, --query <query>` | Search query (Sentry search syntax) |
 | `--full` | Include full event body (stacktraces) |
-| `-t, --period <period>` | Time period (e.g., "1h", "24h", "7d", "30d") (default: "7d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" (default: "7d") |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-c, --cursor <cursor>` | Navigate pages: "next", "prev", "first" (or raw cursor string) |
 

docs/src/content/docs/commands/log.md

@@ -24,7 +24,7 @@ List logs from a project
 | `-n, --limit <limit>` | Number of log entries (1-1000) (default: "100") |
 | `-q, --query <query>` | Filter query (Sentry search syntax) |
 | `-f, --follow <follow>` | Stream logs (optionally specify poll interval in seconds) |
-| `-t, --period <period>` | Time period (e.g., "30d", "14d", "24h"). Default: 30d (project mode), 14d (trace mode) |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" |
 | `-s, --sort <sort>` | Sort order: "newest" (default) or "oldest" (default: "newest") |
 | `--fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 

docs/src/content/docs/commands/span.md

@@ -24,7 +24,7 @@ List spans in a project or trace
 | `-n, --limit <limit>` | Number of spans (<=1000) (default: "25") |
 | `-q, --query <query>` | Filter spans (e.g., "op:db", "duration:>100ms", "project:backend") |
 | `-s, --sort <sort>` | Sort order: date, duration (default: "date") |
-| `-t, --period <period>` | Time period (e.g., "1h", "24h", "7d", "30d") (default: "7d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" (default: "7d") |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-c, --cursor <cursor>` | Navigate pages: "next", "prev", "first" (or raw cursor string) |
 

docs/src/content/docs/commands/trace.md

@@ -24,7 +24,7 @@ List recent traces in a project
 | `-n, --limit <limit>` | Number of traces (1-1000) (default: "25") |
 | `-q, --query <query>` | Search query (Sentry search syntax) |
 | `-s, --sort <sort>` | Sort by: date, duration (default: "date") |
-| `-t, --period <period>` | Time period (e.g., "1h", "24h", "7d", "30d") (default: "7d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" (default: "7d") |
 | `-f, --fresh` | Bypass cache, re-detect projects, and fetch fresh data |
 | `-c, --cursor <cursor>` | Navigate pages: "next", "prev", "first" (or raw cursor string) |
 
@@ -61,7 +61,7 @@ View logs associated with a trace
 | Option | Description |
 |--------|-------------|
 | `-w, --web` | Open trace in browser |
-| `-t, --period <period>` | Time period to search (e.g., "14d", "7d", "24h"). Default: 14d (default: "14d") |
+| `-t, --period <period>` | Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" (default: "14d") |
 | `-n, --limit <limit>` | Number of log entries (<=1000) (default: "100") |
 | `-q, --query <query>` | Additional filter query (Sentry search syntax) |
 | `-s, --sort <sort>` | Sort order: "newest" (default) or "oldest" (default: "newest") |

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

@@ -42,7 +42,7 @@ View a dashboard
 - `-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")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07"`
 
 **Examples:**
 

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

@@ -28,7 +28,7 @@ List events for an issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time period (e.g., "1h", "24h", "7d", "30d") - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List issues in a project
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-n, --limit <value> - Maximum number of issues to list - (default: "25")`
 - `-s, --sort <value> - Sort by: date, new, freq, user - (default: "date")`
-- `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "90d")`
 - `-c, --cursor <value> - Pagination cursor (use "next" for next page, "prev" for previous)`
 - `--compact - Single-line rows for compact output (auto-detects if omitted)`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
@@ -78,7 +78,7 @@ List events for a specific issue
 - `-n, --limit <value> - Number of events (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `--full - Include full event body (stacktraces)`
-- `-t, --period <value> - Time period (e.g., "1h", "24h", "7d", "30d") - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List logs from a project
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Filter query (Sentry search syntax)`
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
-- `-t, --period <value> - Time period (e.g., "30d", "14d", "24h"). Default: 30d (project mode), 14d (trace mode)`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07"`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`
 - `--fresh - Bypass cache, re-detect projects, and fetch fresh data`
 

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

@@ -19,7 +19,7 @@ List spans in a project or trace
 - `-n, --limit <value> - Number of spans (<=1000) - (default: "25")`
 - `-q, --query <value> - Filter spans (e.g., "op:db", "duration:>100ms", "project:backend")`
 - `-s, --sort <value> - Sort order: date, duration - (default: "date")`
-- `-t, --period <value> - Time period (e.g., "1h", "24h", "7d", "30d") - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 

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

@@ -19,7 +19,7 @@ List recent traces in a project
 - `-n, --limit <value> - Number of traces (1-1000) - (default: "25")`
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
-- `-t, --period <value> - Time period (e.g., "1h", "24h", "7d", "30d") - (default: "7d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "7d")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
 
@@ -78,7 +78,7 @@ View logs associated with a trace
 
 **Flags:**
 - `-w, --web - Open trace in browser`
-- `-t, --period <value> - Time period to search (e.g., "14d", "7d", "24h"). Default: 14d - (default: "14d")`
+- `-t, --period <value> - Time range: "7d", "2026-03-07..2026-04-07", ">=2026-03-07" - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (<=1000) - (default: "100")`
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
 - `-s, --sort <value> - Sort order: "newest" (default) or "oldest" - (default: "newest")`

src/commands/dashboard/view.ts

@@ -22,6 +22,11 @@ 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 {
+  PERIOD_BRIEF,
+  parsePeriod,
+  timeRangeToSeconds,
+} from "../../lib/time-range.js";
 import type {
   DashboardWidget,
   WidgetDataResult,
@@ -175,7 +180,7 @@ export const viewCommand = buildCommand({
       period: {
         kind: "parsed",
         parse: String,
-        brief: 'Time period override (e.g., "24h", "7d", "14d")',
+        brief: PERIOD_BRIEF,
         optional: true,
       },
     },
@@ -213,7 +218,14 @@ export const viewCommand = buildCommand({
     );
 
     const regionUrl = await resolveOrgRegion(orgSlug);
-    const period = flags.period ?? dashboard.period ?? "24h";
+    const effectivePeriod = flags.period ?? dashboard.period ?? "24h";
+    const timeRange = parsePeriod(effectivePeriod);
+    const periodSeconds = timeRangeToSeconds(timeRange);
+    // WidgetQueryOptions uses `period` (not `statsPeriod`) for the relative field
+    const widgetTimeOpts =
+      timeRange.type === "relative"
+        ? { period: timeRange.period }
+        : { start: timeRange.start, end: timeRange.end };
     const widgets = dashboard.widgets ?? [];
 
     if (flags.refresh !== undefined) {
@@ -244,12 +256,12 @@ export const viewCommand = buildCommand({
             regionUrl,
             orgSlug,
             dashboard,
-            { period }
+            { ...widgetTimeOpts, periodSeconds }
           );
 
           // Build output data before clearing so clear→render is instantaneous
           const viewData = buildViewData(dashboard, widgetData, widgets, {
-            period,
+            period: effectivePeriod,
             url,
           });
 
@@ -271,11 +283,18 @@ export const viewCommand = buildCommand({
     // ── Single fetch mode ──
     const widgetData = await withProgress(
       { message: "Querying widget data...", json: flags.json },
-      () => queryAllWidgets(regionUrl, orgSlug, dashboard, { period })
+      () =>
+        queryAllWidgets(regionUrl, orgSlug, dashboard, {
+          ...widgetTimeOpts,
+          periodSeconds,
+        })
     );
 
     yield new CommandOutput(
-      buildViewData(dashboard, widgetData, widgets, { period, url })
+      buildViewData(dashboard, widgetData, widgets, {
+        period: effectivePeriod,
+        url,
+      })
     );
     return { hint: `Dashboard: ${url}` };
   },

src/commands/event/list.ts

@@ -19,6 +19,11 @@ import { ContextError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildListCommand, paginationHint } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
+import {
+  parsePeriod,
+  serializeTimeRange,
+  timeRangeToApiParams,
+} from "../../lib/time-range.js";
 import { IssueEventSchema } from "../../types/index.js";
 import {
   buildCommandHint,
@@ -109,6 +114,7 @@ export const listCommand = buildListCommand("event", {
     }
 
     const { cwd } = this;
+    const timeRange = parsePeriod(flags.period);
 
     // Resolve issue using shared resolution logic (supports @latest, short IDs, etc.)
     const { org, issue } = await resolveIssue({
@@ -130,7 +136,7 @@ export const listCommand = buildListCommand("event", {
     const contextKey = buildPaginationContextKey(
       "event-list",
       `${org}/${issue.id}`,
-      { q: flags.query, period: flags.period }
+      { q: flags.query, period: serializeTimeRange(timeRange) }
     );
     const { cursor, direction } = resolveCursor(
       flags.cursor,
@@ -149,7 +155,7 @@ export const listCommand = buildListCommand("event", {
           query: flags.query,
           full: flags.full,
           cursor,
-          statsPeriod: flags.period,
+          ...timeRangeToApiParams(timeRange),
         })
     );
 

src/commands/issue/events.ts

@@ -16,6 +16,11 @@ import { ContextError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildListCommand, paginationHint } from "../../lib/list-command.js";
 import { withProgress } from "../../lib/polling.js";
+import {
+  parsePeriod,
+  serializeTimeRange,
+  timeRangeToApiParams,
+} from "../../lib/time-range.js";
 import { IssueEventSchema } from "../../types/index.js";
 import {
   appendEventsFlags,
@@ -92,6 +97,7 @@ export const eventsCommand = buildListCommand("issue", {
   },
   async *func(this: SentryContext, flags: EventsFlags, issueArg: string) {
     const { cwd } = this;
+    const timeRange = parsePeriod(flags.period);
 
     // Resolve issue using shared resolution logic (supports @latest, short IDs, etc.)
     const { org, issue } = await resolveIssue({
@@ -112,7 +118,7 @@ export const eventsCommand = buildListCommand("issue", {
     const contextKey = buildPaginationContextKey(
       "issue-events",
       `${org}/${issue.id}`,
-      { q: flags.query, period: flags.period }
+      { q: flags.query, period: serializeTimeRange(timeRange) }
     );
     const { cursor, direction } = resolveCursor(
       flags.cursor,
@@ -131,7 +137,7 @@ export const eventsCommand = buildListCommand("issue", {
           query: flags.query,
           full: flags.full,
           cursor,
-          statsPeriod: flags.period,
+          ...timeRangeToApiParams(timeRange),
         })
     );