feat(cli): add explore time series

apps/cli-docs/src/fragments/commands/explore.md

@@ -1,5 +1,31 @@
 
 
+## Time series
+
+Use `--time-series` (`-b`) to see how an aggregate changes over time. The target,
+`--query`, `--environment`, and `--period` filters work as they do for tabular
+queries. Without `--field`, temporal queries count matching events in each time
+bucket. For performance analysis, select aggregates such as `p95(span.duration)`;
+repeat `--field` to request more than one series.
+
+With no value or `auto`, the CLI chooses a bucket interval from the requested time range.
+Pass a duration, such as `--time-series 15m` or `-b 15m`, to set the bucket width.
+When omitting the value, place an explicit target before the flag.
+Use `--period` (`-t`) to set the overall time range. Each invocation returns a
+snapshot and exits; it does not follow live data.
+
+Temporal queries support errors, spans, logs, and metrics. Metrics require
+`--metric` or an explicit aggregate in the raw tracemetrics format described
+below. Grouping columns, replays, `--sort`, `--limit`, and `--cursor` are not
+supported in temporal mode. Use a tabular query to break down a series by a field
+or inspect individual events.
+
+JSON output includes `timeSeries`, `meta`, and `dataset`. Each series retains its
+bucket timestamps, values, and available sampling or completeness metadata.
+Null values remain null, and incomplete buckets remain marked as incomplete;
+recent buckets may still be waiting for ingestion or for the interval to end.
+Temporal output has no pagination cursor.
+
 ## Metrics
 
 Use `--metric` (`-m`) to query metrics by name. The CLI auto-resolves the metric's type and unit.

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/explore.md

@@ -29,7 +29,8 @@ Query aggregate event data (Explore)
 - `-q, --query <value> - Search query (Sentry search syntax)`
 - `-s, --sort <value> - Sort field (prefix with - for desc, e.g., "-count()")`
 - `-e, --environment <value>... - Environment filter (repeatable, comma-separated)`
-- `-n, --limit <value> - Number of rows (1-1000) - (default: "25")`
+- `-n, --limit <value> - Number of table rows (1-1000, default: 25)`
+- `-b, --time-series <value> - Query time series (default: auto; optional bucket duration, e.g., 15m)`
 - `-t, --period <value> - Time range: "7d", "2024-01-01..2024-02-01", ">=2024-01-01" - (default: "24h")`
 - `-f, --fresh - Bypass cache, re-detect projects, and fetch fresh data`
 - `-c, --cursor <value> - Navigate pages: "next", "prev", "first" (or raw cursor string)`
@@ -67,6 +68,15 @@ sentry explore my-org/cli -F span.op -F "p50(span.duration)" -F "p95(span.durati
 # Top spans by count
 sentry explore my-org/cli -F span.op -F "count()" --dataset spans --sort "-count()"
 
+# Error counts in 15-minute buckets over the last hour
+sentry explore my-org/cli --time-series 15m --period 1h
+
+# Latency over time with automatic bucket duration, as JSON
+sentry explore my-org/cli --dataset spans -F "p95(span.duration)" --time-series --period 24h --json
+
+# A metric over time using its discovered type and unit
+sentry explore my-org/cli --dataset metrics -m cache.hit_rate --agg avg -b -t 1h
+
 # Sum a custom metric (e.g., LLM token usage) across an organization
 sentry explore my-org/ -m llm.token_usage --dataset metrics --period 7d
 

packages/cli/script/generate-sdk.ts

@@ -141,8 +141,12 @@ function inferFlagType(def: FlagDef): {
     };
   }
 
-  // kind === "parsed" — infer from default value
+  // Optional numeric flags may have no parser default; their placeholder
+  // preserves the input type without making the default appear explicit.
   const numberType = f.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword);
+  if (def.placeholder === "number") {
+    return { type: numberType, kind: "parsed" };
+  }
   if (def.default !== undefined && typeof def.default === "number") {
     return { type: numberType, kind: "parsed" };
   }