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

## Summary

Overload the existing `--period` flag across all 8 time-scoped commands
to accept absolute date ranges using `gh`-compatible syntax (e.g., `gh
search issues --created ">2023-01-01"`), in addition to existing
relative durations.

## New syntax

| Syntax | Meaning | Example |
|--------|---------|---------|
| `7d`, `24h` | Relative (unchanged) | `--period 7d` |
| `date..date` | Full range | `--period "2024-01-01..2024-02-01"` |
| `date..` / `..date` | Open-ended | `--period "2024-01-01.."` |
| `>=date` | From (inclusive) | `--period ">=2024-01-01"` |
| `>date` | After (exclusive) | `--period ">2024-01-01"` |
| `<=date` | Through (inclusive) | `--period "<=2024-02-01"` |
| `<date` | Before (exclusive) | `--period "<2024-02-01"` |

Date formats: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, with optional
timezone.

## Key design decisions

- **Single flag** — no new `--start`/`--end` flags, avoids alias
conflicts and `--help` clutter
- **Local timezone** for date-only inputs — `"2024-01-15"` means the
user's local midnight, not UTC
- **Exclusive operators shift dates** — `>2024-01-15` (date-only) starts
from Jan 16; `>2024-01-15T12:00:00Z` (datetime) passes through as-is
- **Follow mode validation** — `log list --follow` rejects end-bounded
ranges
- **Pagination cache** — serialization normalizes to UTC for
deterministic keys; `>=2024-01-01` and `2024-01-01..` share the same
cache entry

## Affected commands (8)

`trace list`, `span list`, `issue events`, `event list`, `issue list`,
`trace logs`, `log list`, `dashboard view`

## Changes

- **New**: `src/lib/time-range.ts` — `parsePeriod()`,
`timeRangeToApiParams()`, `serializeTimeRange()`, `timeRangeToSeconds()`
- **API layer**: Added `start?`/`end?` to all option types in
`api/traces.ts`, `api/events.ts`, `api/issues.ts`, `api/logs.ts`,
`api/dashboards.ts`
- **Commands**: All 8 commands parse period via `parsePeriod()`, spread
API params via `timeRangeToApiParams()`, serialize for pagination via
`serializeTimeRange()`
- **Tests**: 67 new tests (34 unit + 33 property-based with fast-check)

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: BYK

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`