feat(telemetry): auto-capture command flags as Sentry tags

BYK · BYK · commit 2e830bfe9f9f · 2026-02-09T10:26:43.000Z
Add buildCommand wrapper that automatically captures flag values as
telemetry tags (e.g., flag.verbose, flag.no-modify-path). Commands
just need to import buildCommand from lib/command.js instead of
@stricli/core - no other changes needed.

- Add setFlagContext() helper in telemetry.ts
- Add buildCommand wrapper in new lib/command.ts
- Update all 19 commands to use the wrapper
diff --git a/src/commands/auth/login.ts b/src/commands/auth/login.ts
@@ -1,6 +1,6 @@
-import { buildCommand, numberParser } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { getCurrentUser, getUserRegions } from "../../lib/api-client.js";
+import { buildCommand, numberParser } from "../../lib/command.js";
 import { clearAuth, isAuthenticated, setAuthToken } from "../../lib/db/auth.js";
 import { getDbPath } from "../../lib/db/index.js";
 import { setUserInfo } from "../../lib/db/user.js";
diff --git a/src/commands/auth/logout.ts b/src/commands/auth/logout.ts
@@ -4,8 +4,8 @@
  * Clear stored authentication credentials.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { clearAuth, isAuthenticated } from "../../lib/db/auth.js";
 import { getDbPath } from "../../lib/db/index.js";
 import { success } from "../../lib/formatters/colors.js";
diff --git a/src/commands/auth/refresh.ts b/src/commands/auth/refresh.ts
@@ -4,8 +4,8 @@
  * Manually refresh the authentication token.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { getAuthConfig, refreshToken } from "../../lib/db/auth.js";
 import { AuthError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
diff --git a/src/commands/auth/status.ts b/src/commands/auth/status.ts
@@ -4,9 +4,9 @@
  * Display authentication status and verify credentials.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { listOrganizations } from "../../lib/api-client.js";
+import { buildCommand } from "../../lib/command.js";
 import {
   type AuthConfig,
   getAuthConfig,
diff --git a/src/commands/auth/token.ts b/src/commands/auth/token.ts
@@ -5,8 +5,8 @@
  * Useful for piping to other commands or scripts.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { getAuthToken } from "../../lib/db/auth.js";
 import { AuthError } from "../../lib/errors.js";
 
diff --git a/src/commands/cli/feedback.ts b/src/commands/cli/feedback.ts
@@ -10,8 +10,8 @@
 
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/bun";
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { ValidationError } from "../../lib/errors.js";
 
 export const feedbackCommand = buildCommand({
diff --git a/src/commands/cli/fix.ts b/src/commands/cli/fix.ts
@@ -4,8 +4,8 @@
  * Diagnose and repair CLI database issues.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { getDbPath, getRawDatabase } from "../../lib/db/index.js";
 import {
   CURRENT_SCHEMA_VERSION,
diff --git a/src/commands/cli/setup.ts b/src/commands/cli/setup.ts
@@ -6,8 +6,8 @@
  */
 
 import { dirname } from "node:path";
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { installCompletions } from "../../lib/completions.js";
 import { CLI_VERSION } from "../../lib/constants.js";
 import { setInstallInfo } from "../../lib/db/install-info.js";
diff --git a/src/commands/cli/upgrade.ts b/src/commands/cli/upgrade.ts
@@ -4,8 +4,8 @@
  * Self-update the Sentry CLI to the latest or a specific version.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { CLI_VERSION } from "../../lib/constants.js";
 import { setInstallInfo } from "../../lib/db/install-info.js";
 import { UpgradeError } from "../../lib/errors.js";
diff --git a/src/commands/event/view.ts b/src/commands/event/view.ts
@@ -4,7 +4,6 @@
  * View detailed information about a Sentry event.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { findProjectsBySlug, getEvent } from "../../lib/api-client.js";
 import {
@@ -13,6 +12,7 @@ import {
   spansFlag,
 } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
+import { buildCommand } from "../../lib/command.js";
 import { ContextError, ValidationError } from "../../lib/errors.js";
 import { formatEventDetails, writeJson } from "../../lib/formatters/index.js";
 import { resolveOrgAndProject } from "../../lib/resolve-target.js";
diff --git a/src/commands/issue/explain.ts b/src/commands/issue/explain.ts
@@ -4,8 +4,8 @@
  * Get root cause analysis for a Sentry issue using Seer AI.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
+import { buildCommand } from "../../lib/command.js";
 import { ApiError } from "../../lib/errors.js";
 import { writeFooter, writeJson } from "../../lib/formatters/index.js";
 import {
diff --git a/src/commands/issue/list.ts b/src/commands/issue/list.ts
@@ -5,7 +5,6 @@
  * Supports monorepos with multiple detected projects.
  */
 
-import { buildCommand, numberParser } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { buildOrgAwareAliases } from "../../lib/alias.js";
 import {
@@ -14,6 +13,7 @@ import {
   listProjects,
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
+import { buildCommand, numberParser } from "../../lib/command.js";
 import {
   clearProjectAliases,
   setProjectAliases,
diff --git a/src/commands/issue/plan.ts b/src/commands/issue/plan.ts
@@ -5,9 +5,9 @@
  * Automatically runs root cause analysis if not already done.
  */
 
-import { buildCommand, numberParser } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { triggerSolutionPlanning } from "../../lib/api-client.js";
+import { buildCommand, numberParser } from "../../lib/command.js";
 import { ApiError, ValidationError } from "../../lib/errors.js";
 import { muted } from "../../lib/formatters/colors.js";
 import { writeJson } from "../../lib/formatters/index.js";
diff --git a/src/commands/issue/view.ts b/src/commands/issue/view.ts
@@ -4,11 +4,11 @@
  * View detailed information about a Sentry issue.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { getLatestEvent } from "../../lib/api-client.js";
 import { spansFlag } from "../../lib/arg-parsing.js";
 import { openInBrowser } from "../../lib/browser.js";
+import { buildCommand } from "../../lib/command.js";
 import {
   formatEventDetails,
   formatIssueDetails,
diff --git a/src/commands/log/list.ts b/src/commands/log/list.ts
@@ -7,10 +7,10 @@
 
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/bun";
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { findProjectsBySlug, listLogs } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
+import { buildCommand } from "../../lib/command.js";
 import { AuthError, ContextError } from "../../lib/errors.js";
 import {
   formatLogRow,
diff --git a/src/commands/org/list.ts b/src/commands/org/list.ts
@@ -4,9 +4,9 @@
  * List organizations the user has access to.
  */
 
-import { buildCommand, numberParser } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { listOrganizations } from "../../lib/api-client.js";
+import { buildCommand, numberParser } from "../../lib/command.js";
 import { DEFAULT_SENTRY_HOST } from "../../lib/constants.js";
 import { getAllOrgRegions } from "../../lib/db/regions.js";
 import {
diff --git a/src/commands/org/view.ts b/src/commands/org/view.ts
@@ -4,10 +4,10 @@
  * View detailed information about a Sentry organization.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { getOrganization } from "../../lib/api-client.js";
 import { openInBrowser } from "../../lib/browser.js";
+import { buildCommand } from "../../lib/command.js";
 import { ContextError } from "../../lib/errors.js";
 import { formatOrgDetails, writeOutput } from "../../lib/formatters/index.js";
 import { resolveOrg } from "../../lib/resolve-target.js";
diff --git a/src/commands/project/list.ts b/src/commands/project/list.ts
@@ -4,9 +4,9 @@
  * List projects in an organization.
  */
 
-import { buildCommand, numberParser } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { listOrganizations, listProjects } from "../../lib/api-client.js";
+import { buildCommand, numberParser } from "../../lib/command.js";
 import { getDefaultOrganization } from "../../lib/db/defaults.js";
 import { AuthError } from "../../lib/errors.js";
 import {
diff --git a/src/commands/project/view.ts b/src/commands/project/view.ts
@@ -5,10 +5,10 @@
  * Supports monorepos with multiple detected projects.
  */
 
-import { buildCommand } from "@stricli/core";
 import type { SentryContext } from "../../context.js";
 import { getProject, getProjectKeys } from "../../lib/api-client.js";
 import { openInBrowser } from "../../lib/browser.js";
+import { buildCommand } from "../../lib/command.js";
 import { AuthError, ContextError } from "../../lib/errors.js";
 import {
   divider,
diff --git a/src/lib/command.ts b/src/lib/command.ts
@@ -0,0 +1,95 @@
+/**
+ * Command Builder with Telemetry
+ *
+ * Wraps Stricli's buildCommand to automatically capture flag usage for telemetry.
+ * Commands should import buildCommand from this module instead of @stricli/core.
+ */
+
+import {
+  type Command,
+  type CommandContext,
+  type CommandFunction,
+  buildCommand as stricliCommand,
+  numberParser as stricliNumberParser,
+} from "@stricli/core";
+import { setFlagContext } from "./telemetry.js";
+
+/**
+ * Parse a string input as a number.
+ * Re-exported from Stricli for convenience.
+ */
+export const numberParser = stricliNumberParser;
+
+/** Base flags type from Stricli */
+type BaseFlags = Readonly<Partial<Record<string, unknown>>>;
+
+/** Base args type from Stricli */
+type BaseArgs = readonly unknown[];
+
+/** Command documentation */
+type CommandDocumentation = {
+  readonly brief: string;
+  readonly fullDescription?: string;
+};
+
+/**
+ * Arguments for building a command with a local function.
+ * This is the subset of Stricli's CommandBuilderArguments that we support.
+ */
+type LocalCommandBuilderArguments<
+  FLAGS extends BaseFlags,
+  ARGS extends BaseArgs,
+  CONTEXT extends CommandContext,
+> = {
+  readonly parameters?: Record<string, unknown>;
+  readonly docs: CommandDocumentation;
+  readonly func: CommandFunction<FLAGS, ARGS, CONTEXT>;
+};
+
+/**
+ * Build a command with automatic flag telemetry.
+ *
+ * This is a drop-in replacement for Stricli's buildCommand that wraps the
+ * command function to automatically capture flag values as Sentry tags.
+ *
+ * Usage is identical to Stricli's buildCommand - just change the import:
+ * ```ts
+ * // Before:
+ * import { buildCommand } from "@stricli/core";
+ *
+ * // After:
+ * import { buildCommand } from "../../lib/command.js";
+ * ```
+ *
+ * @param builderArgs - Same arguments as Stricli's buildCommand
+ * @returns A Command with automatic flag telemetry
+ */
+export function buildCommand<
+  const FLAGS extends BaseFlags = NonNullable<unknown>,
+  const ARGS extends BaseArgs = [],
+  const CONTEXT extends CommandContext = CommandContext,
+>(
+  builderArgs: LocalCommandBuilderArguments<FLAGS, ARGS, CONTEXT>
+): Command<CONTEXT> {
+  const originalFunc = builderArgs.func;
+
+  // Wrap the function to capture flags before execution
+  const wrappedFunc = function (
+    this: CONTEXT,
+    flags: FLAGS,
+    ...args: ARGS
+  ): ReturnType<typeof originalFunc> {
+    // Capture flag values as telemetry tags
+    setFlagContext(flags as Record<string, unknown>);
+
+    // Call the original function with the same context and arguments
+    return originalFunc.call(this, flags, ...args);
+  } as typeof originalFunc;
+
+  // Build the command with the wrapped function
+  return stricliCommand({
+    ...builderArgs,
+    func: wrappedFunc,
+    // biome-ignore lint/suspicious/noExplicitAny: Stricli types are complex unions
+  } as any);
+}
diff --git a/src/lib/telemetry.ts b/src/lib/telemetry.ts
@@ -214,6 +214,62 @@ export function setOrgProjectContext(orgs: string[], projects: string[]): void {
   }
 }
 
+/**
+ * Set command flags as telemetry tags.
+ *
+ * Converts flag names from camelCase to kebab-case and sets them as tags
+ * with the `flag.` prefix (e.g., `flag.no-modify-path`).
+ *
+ * Only sets tags for flags with non-default/meaningful values:
+ * - Boolean flags: only when true
+ * - String/number flags: only when defined and non-empty
+ * - Array flags: only when non-empty
+ *
+ * Call this at the start of command func() to instrument flag usage.
+ *
+ * @param flags - The parsed flags object from Stricli
+ *
+ * @example
+ * ```ts
+ * async func(this: SentryContext, flags: MyFlags): Promise<void> {
+ *   setFlagContext(flags);
+ *   // ... command implementation
+ * }
+ * ```
+ */
+export function setFlagContext(flags: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(flags)) {
+    // Skip undefined/null values
+    if (value === undefined || value === null) {
+      continue;
+    }
+
+    // Skip false booleans (default state)
+    if (value === false) {
+      continue;
+    }
+
+    // Skip empty strings
+    if (value === "") {
+      continue;
+    }
+
+    // Skip empty arrays
+    if (Array.isArray(value) && value.length === 0) {
+      continue;
+    }
+
+    // Convert camelCase to kebab-case for consistency with CLI flag names
+    const kebabKey = key.replace(/([A-Z])/g, "-$1").toLowerCase();
+
+    // Set the tag with flag. prefix
+    // For booleans, just set "true"; for other types, convert to string
+    const tagValue =
+      typeof value === "boolean" ? "true" : String(value).slice(0, 200); // Truncate long values
+    Sentry.setTag(`flag.${kebabKey}`, tagValue);
+  }
+}
+
 /**
  * Wrap an operation with a Sentry span for tracing.
  *
diff --git a/test/lib/command.test.ts b/test/lib/command.test.ts
diff --git a/test/lib/telemetry.test.ts b/test/lib/telemetry.test.ts
