feat: add response caching for read-only API calls

package.json

@@ -14,6 +14,7 @@
     "@stricli/auto-complete": "^1.2.4",
     "@stricli/core": "^1.2.4",
     "@types/bun": "latest",
+    "@types/http-cache-semantics": "^4.2.0",
     "@types/node": "^22",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/semver": "^7.7.1",
@@ -22,6 +23,7 @@
     "cli-highlight": "^2.1.11",
     "esbuild": "^0.25.0",
     "fast-check": "^4.5.3",
+    "http-cache-semantics": "^4.2.0",
     "ignore": "^7.0.5",
     "marked": "^15",
     "p-limit": "^7.2.0",

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

@@ -89,6 +89,7 @@ View authentication status
 
 **Flags:**
 - `--show-token - Show the stored token (masked by default)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -106,6 +107,7 @@ Show the currently authenticated user
 
 **Flags:**
 - `--json - Output as JSON`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Org
 
@@ -118,6 +120,7 @@ List organizations
 **Flags:**
 - `-n, --limit <value> - Maximum number of organizations to list - (default: "30")`
 - `--json - Output JSON`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -134,6 +137,7 @@ View details of an organization
 **Flags:**
 - `--json - Output as JSON`
 - `-w, --web - Open in browser`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -166,6 +170,7 @@ List projects
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-p, --platform <value> - Filter by platform (e.g., javascript, python)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -187,6 +192,7 @@ View details of a project
 **Flags:**
 - `--json - Output as JSON`
 - `-w, --web - Open in browser`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -220,6 +226,7 @@ List issues in a project
 - `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor for <org>/ or multi-target modes (use "last" to continue)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -264,6 +271,7 @@ Analyze an issue's root cause using Seer AI
 **Flags:**
 - `--json - Output as JSON`
 - `--force - Force new analysis even if one exists`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -291,6 +299,7 @@ Generate a solution plan using Seer AI
 - `--cause <value> - Root cause ID to plan (required if multiple causes exist)`
 - `--json - Output as JSON`
 - `--force - Force new plan even if one exists`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -318,6 +327,7 @@ View details of a specific issue
 - `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -345,6 +355,7 @@ View details of a specific event
 - `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -467,6 +478,7 @@ List repositories
 - `-n, --limit <value> - Maximum number of repositories to list - (default: "30")`
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Team
 
@@ -480,6 +492,7 @@ List teams
 - `-n, --limit <value> - Maximum number of teams to list - (default: "30")`
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -510,6 +523,7 @@ List logs from a project
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
 - `--trace <value> - Filter logs by trace ID (32-character hex string)`
 - `--json - Output as JSON`
+- `--fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -555,6 +569,7 @@ View details of a specific log entry
 **Flags:**
 - `--json - Output as JSON`
 - `-w, --web - Open in browser`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 **Examples:**
 
@@ -591,6 +606,7 @@ List recent traces in a project
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `--json - Output as JSON`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 #### `sentry trace view <args...>`
 
@@ -600,6 +616,7 @@ View details of a specific trace
 - `--json - Output as JSON`
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 #### `sentry trace logs <args...>`
 
@@ -611,6 +628,7 @@ View logs associated with a trace
 - `-t, --period <value> - Time period to search (e.g., "14d", "7d", "24h"). Default: 14d - (default: "14d")`
 - `-n, --limit <value> - Number of log entries (1-1000) - (default: "100")`
 - `-q, --query <value> - Additional filter query (Sentry search syntax)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Issues
 
@@ -627,6 +645,7 @@ List issues in a project
 - `-t, --period <value> - Time period for issue activity (e.g. 24h, 14d, 90d) - (default: "90d")`
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor for <org>/ or multi-target modes (use "last" to continue)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Orgs
 
@@ -639,6 +658,7 @@ List organizations
 **Flags:**
 - `-n, --limit <value> - Maximum number of organizations to list - (default: "30")`
 - `--json - Output JSON`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Projects
 
@@ -653,6 +673,7 @@ List projects
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `-p, --platform <value> - Filter by platform (e.g., javascript, python)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Repos
 
@@ -666,6 +687,7 @@ List repositories
 - `-n, --limit <value> - Maximum number of repositories to list - (default: "30")`
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Teams
 
@@ -679,6 +701,7 @@ List teams
 - `-n, --limit <value> - Maximum number of teams to list - (default: "30")`
 - `--json - Output JSON`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Logs
 
@@ -694,6 +717,7 @@ List logs from a project
 - `-f, --follow <value> - Stream logs (optionally specify poll interval in seconds)`
 - `--trace <value> - Filter logs by trace ID (32-character hex string)`
 - `--json - Output as JSON`
+- `--fresh - Bypass cache and fetch fresh data`
 
 ### Traces
 
@@ -709,6 +733,7 @@ List recent traces in a project
 - `-s, --sort <value> - Sort by: date, duration - (default: "date")`
 - `-c, --cursor <value> - Pagination cursor (use "last" to continue from previous page)`
 - `--json - Output as JSON`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ### Whoami
 
@@ -720,6 +745,7 @@ Show the currently authenticated user
 
 **Flags:**
 - `--json - Output as JSON`
+- `-f, --fresh - Bypass cache and fetch fresh data`
 
 ## Output Formats
 

src/commands/auth/login.ts

@@ -8,6 +8,7 @@ import { AuthError } from "../../lib/errors.js";
 import { muted, success } from "../../lib/formatters/colors.js";
 import { formatUserIdentity } from "../../lib/formatters/human.js";
 import { runInteractiveLogin } from "../../lib/interactive-login.js";
+import { clearResponseCache } from "../../lib/response-cache.js";
 
 type LoginFlags = {
   readonly token?: string;
@@ -52,6 +53,13 @@ export const loginCommand = buildCommand({
 
     // Token-based authentication
     if (flags.token) {
+      // Clear stale cached responses from a previous session
+      try {
+        await clearResponseCache();
+      } catch {
+        // Non-fatal: cache directory may not exist
+      }
+
       // Save token first, then validate by fetching user regions
       await setAuthToken(flags.token);
 
@@ -90,6 +98,13 @@ export const loginCommand = buildCommand({
       return;
     }
 
+    // Clear stale cached responses from a previous session
+    try {
+      await clearResponseCache();
+    } catch {
+      // Non-fatal: cache directory may not exist
+    }
+
     // Device Flow OAuth
     const loginSuccess = await runInteractiveLogin(
       stdout,

src/commands/auth/status.ts

@@ -25,10 +25,16 @@ import {
   formatUserIdentity,
   maskToken,
 } from "../../lib/formatters/human.js";
+import {
+  applyFreshFlag,
+  FRESH_ALIASES,
+  FRESH_FLAG,
+} from "../../lib/list-command.js";
 import type { Writer } from "../../types/index.js";
 
 type StatusFlags = {
   readonly "show-token": boolean;
+  readonly fresh: boolean;
 };
 
 /**
@@ -131,9 +137,12 @@ export const statusCommand = buildCommand({
         brief: "Show the stored token (masked by default)",
         default: false,
       },
+      fresh: FRESH_FLAG,
     },
+    aliases: FRESH_ALIASES,
   },
   async func(this: SentryContext, flags: StatusFlags): Promise<void> {
+    applyFreshFlag(flags);
     const { stdout, stderr } = this;
 
     const auth = await getAuthConfig();

src/commands/auth/whoami.ts

@@ -13,9 +13,15 @@ import { isAuthenticated } from "../../lib/db/auth.js";
 import { setUserInfo } from "../../lib/db/user.js";
 import { AuthError } from "../../lib/errors.js";
 import { formatUserIdentity, writeJson } from "../../lib/formatters/index.js";
+import {
+  applyFreshFlag,
+  FRESH_ALIASES,
+  FRESH_FLAG,
+} from "../../lib/list-command.js";
 
 type WhoamiFlags = {
   readonly json: boolean;
+  readonly fresh: boolean;
 };
 
 export const whoamiCommand = buildCommand({
@@ -33,9 +39,12 @@ export const whoamiCommand = buildCommand({
         brief: "Output as JSON",
         default: false,
       },
+      fresh: FRESH_FLAG,
     },
+    aliases: FRESH_ALIASES,
   },
   async func(this: SentryContext, flags: WhoamiFlags): Promise<void> {
+    applyFreshFlag(flags);
     const { stdout } = this;
 
     if (!(await isAuthenticated())) {

src/commands/event/view.ts

@@ -21,6 +21,11 @@ import { openInBrowser } from "../../lib/browser.js";
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ResolutionError } from "../../lib/errors.js";
 import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
+import {
+  applyFreshFlag,
+  FRESH_ALIASES,
+  FRESH_FLAG,
+} from "../../lib/list-command.js";
 import { resolveEffectiveOrg } from "../../lib/region.js";
 import {
   resolveOrgAndProject,
@@ -38,6 +43,7 @@ type ViewFlags = {
   readonly json: boolean;
   readonly web: boolean;
   readonly spans: number;
+  readonly fresh: boolean;
 };
 
 type HumanOutputOptions = {
@@ -301,14 +307,16 @@ export const viewCommand = buildCommand({
         default: false,
       },
       ...spansFlag,
+      fresh: FRESH_FLAG,
     },
-    aliases: { w: "web" },
+    aliases: { ...FRESH_ALIASES, w: "web" },
   },
   async func(
     this: SentryContext,
     flags: ViewFlags,
     ...args: string[]
   ): Promise<void> {
+    applyFreshFlag(flags);
     const { stdout, cwd } = this;
 
     // Parse positional args