fix(logger): inject --verbose and --log-level as proper Stricli flags

Fix three bugs in the logging system introduced in #338:

1. `--verbose` rejected by all commands except `api` — Stricli throws
   "No flag registered for --verbose" because extractLogLevelFromArgs
   intentionally left it in argv for the api command.

2. `--log-level=debug` (equals form) not handled — argv.indexOf only
   matched the space-separated form, passing the flag through to Stricli.

3. `SENTRY_LOG_LEVEL` env var has no visible effect — consola withTag()
   creates independent instances that snapshot the level at creation time.
   Module-level scoped loggers never saw later setLogLevel() calls.

Instead of pre-parsing flags from argv (bypassing Stricli), define them as
proper hidden Stricli flags. buildCommand in src/lib/command.ts now wraps
Stricli to inject hidden --log-level (enum) and --verbose (boolean) flags
into every command, intercept them, apply setLogLevel(), then strip them
before calling the original func.

When a command already defines its own --verbose (e.g. api uses it for HTTP
output), the injected one is skipped — the command own value still triggers
debug-level logging as a side-effect.

setLogLevel() now propagates to all withTag() children via a registry,
fixing the env var and flag having no effect on scoped loggers.

Document SENTRY_LOG_LEVEL, --log-level, and --verbose in configuration
docs.

Author: BYK

AGENTS.md

@@ -686,7 +686,7 @@ mock.module("./some-module", () => ({
 * **Shared pagination infrastructure: buildPaginationContextKey and parseCursorFlag**: List commands with cursor pagination use \`buildPaginationContextKey(type, identifier, flags)\` for composite context keys and \`parseCursorFlag(value)\` accepting \`"last"\` magic value. Critical: \`resolveCursor()\` must be called inside the \`org-all\` override closure, not before \`dispatchOrgScopedList\` — otherwise cursor validation errors fire before the correct mode-specific error.
 
 <!-- lore:019cbd5f-ec35-7e2d-8386-6d3a67adf0cf -->
-* **Telemetry instrumentation pattern: withTracingSpan + captureException for handled errors**: For graceful-fallback operations, use \`withTracingSpan\` from \`src/lib/telemetry.ts\` for child spans and \`captureException\` from \`@sentry/bun\` (named import — Biome forbids namespace imports) with \`level: 'warning'\` for non-fatal errors. \`withTracingSpan\` uses \`onlyIfParent: true\` so it's a no-op without active transaction. When returning \`withTracingSpan(...)\` directly, drop \`async\` and use \`Promise.resolve(null)\` for early returns. User-visible fallbacks should use \`log.warn()\` not \`log.debug()\` — debug is invisible at default level. Also: several commands bypass telemetry by importing \`buildCommand\` from \`@stricli/core\` directly instead of \`../../lib/command.js\`. Affected: trace/list, trace/view, log/view, api.ts, help.ts.
+* **Telemetry instrumentation pattern: withTracingSpan + captureException for handled errors**: For graceful-fallback operations, use \`withTracingSpan\` from \`src/lib/telemetry.ts\` for child spans and \`captureException\` from \`@sentry/bun\` (named import — Biome forbids namespace imports) with \`level: 'warning'\` for non-fatal errors. \`withTracingSpan\` uses \`onlyIfParent: true\` so it's a no-op without active transaction. When returning \`withTracingSpan(...)\` directly, drop \`async\` and use \`Promise.resolve(null)\` for early returns. User-visible fallbacks should use \`log.warn()\` not \`log.debug()\` — debug is invisible at default level. \`buildCommand\` in \`src/lib/command.ts\` wraps Stricli's \`buildCommand\` to inject hidden \`--log-level\` (enum) and \`--verbose\` (boolean) flags, telemetry capture, and logging setup into every command. When a command already defines its own \`--verbose\` (e.g. \`api\` uses it for HTTP output), the injected one is skipped — the command's own value still triggers debug-level logging as a side-effect. Consola's \`withTag()\` creates independent instances — \`setLogLevel()\` propagates to all children via a registry.
 
 ### Preference
 

docs/src/content/docs/configuration.md

@@ -89,6 +89,18 @@ Disable CLI telemetry (error tracking for the CLI itself). The CLI sends anonymi
 export SENTRY_CLI_NO_TELEMETRY=1
 ```
 
+### `SENTRY_LOG_LEVEL`
+
+Controls the verbosity of diagnostic output. Defaults to `info`.
+
+Valid values: `error`, `warn`, `log`, `info`, `debug`, `trace`
+
+```bash
+export SENTRY_LOG_LEVEL=debug
+```
+
+Equivalent to passing `--log-level debug` on the command line. CLI flags take precedence over the environment variable.
+
 ### `SENTRY_CLI_NO_UPDATE_CHECK`
 
 Disable the automatic update check that runs periodically in the background.
@@ -97,6 +109,33 @@ Disable the automatic update check that runs periodically in the background.
 export SENTRY_CLI_NO_UPDATE_CHECK=1
 ```
 
+## Global Options
+
+These flags are accepted by every command. They are not shown in individual command `--help` output, but are always available.
+
+### `--log-level <level>`
+
+Set the log verbosity level. Accepts: `error`, `warn`, `log`, `info`, `debug`, `trace`.
+
+```bash
+sentry issue list --log-level debug
+sentry --log-level=trace cli upgrade
+```
+
+Overrides `SENTRY_LOG_LEVEL` when both are set.
+
+### `--verbose`
+
+Shorthand for `--log-level debug`. Enables debug-level diagnostic output.
+
+```bash
+sentry issue list --verbose
+```
+
+:::note
+The `sentry api` command also uses `--verbose` to show full HTTP request/response details. When used with `sentry api`, it serves both purposes (debug logging + HTTP output).
+:::
+
 ## Credential Storage
 
 Credentials are stored in a SQLite database at `~/.sentry/` (or the path set by `SENTRY_CONFIG_DIR`) with restricted file permissions (mode 600) for security. The database also caches:

src/bin.ts

@@ -5,11 +5,7 @@ import { buildContext } from "./context.js";
 import { AuthError, formatError, getExitCode } from "./lib/errors.js";
 import { error } from "./lib/formatters/colors.js";
 import { runInteractiveLogin } from "./lib/interactive-login.js";
-import {
-  extractLogLevelFromArgs,
-  getEnvLogLevel,
-  setLogLevel,
-} from "./lib/logger.js";
+import { getEnvLogLevel, setLogLevel } from "./lib/logger.js";
 import { withTelemetry } from "./lib/telemetry.js";
 import { startCleanupOldBinary } from "./lib/upgrade.js";
 import {
@@ -94,22 +90,14 @@ async function main(): Promise<void> {
 
   const args = process.argv.slice(2);
 
-  // Apply SENTRY_LOG_LEVEL env var first (lazy read, not at module load time).
-  // CLI flags below override this if present.
+  // Apply SENTRY_LOG_LEVEL env var early (lazy read, not at module load time).
+  // CLI flags (--log-level, --verbose) are handled by Stricli via
+  // buildCommand and take priority when present.
   const envLogLevel = getEnvLogLevel();
   if (envLogLevel !== null) {
     setLogLevel(envLogLevel);
   }
 
-  // Extract global log-level flags before Stricli parses args.
-  // --log-level is consumed (removed); --verbose is read but left in place
-  // because some commands (e.g., `api`) define their own --verbose flag.
-  // CLI flags take priority over SENTRY_LOG_LEVEL env var.
-  const logLevel = extractLogLevelFromArgs(args);
-  if (logLevel !== null) {
-    setLogLevel(logLevel);
-  }
-
   const suppressNotification = shouldSuppressNotification(args);
 
   // Start background update check (non-blocking)

src/commands/help.ts

@@ -6,8 +6,9 @@
  * - `sentry help <command>`: Shows Stricli's detailed help (--helpAll) for that command
  */
 
-import { buildCommand, run } from "@stricli/core";
+import { run } from "@stricli/core";
 import type { SentryContext } from "../context.js";
+import { buildCommand } from "../lib/command.js";
 import { printCustomHelp } from "../lib/help.js";
 
 export const helpCommand = buildCommand({

src/lib/command.ts

@@ -1,16 +1,27 @@
 /**
- * Command Builder with Telemetry
+ * Command builder with telemetry and global logging flag injection.
  *
- * Wraps Stricli's buildCommand to automatically capture flag usage for telemetry.
+ * Provides `buildCommand` — the standard command builder for all Sentry CLI
+ * commands. It wraps Stricli's `buildCommand` with:
  *
- * ALL commands MUST import `buildCommand` from this module, NOT from `@stricli/core`.
- * Importing directly from `@stricli/core` silently bypasses flag/arg telemetry capture.
+ * 1. **Automatic flag/arg telemetry** — captures flag values and positional
+ *    arguments as Sentry span context for observability.
  *
- * Correct:   import { buildCommand } from "../../lib/command.js";
- * Incorrect: import { buildCommand } from "@stricli/core";  // skips telemetry!
+ * 2. **Hidden global logging flags** — injects `--log-level` and `--verbose`
+ *    into every command's parameters. These are intercepted before the original
+ *    `func` runs: the logger level is set, and the injected flags are stripped
+ *    so the original function never sees them. If a command already defines its
+ *    own `--verbose` flag (e.g. `api` uses it for HTTP output), the injected
+ *    one is skipped and the command's own value is used for both purposes.
+ *
+ * ALL commands MUST use `buildCommand` from this module, NOT from
+ * `@stricli/core`. Importing directly from Stricli silently bypasses
+ * telemetry and global flag handling.
  *
- * Exception: `help.ts` may import from `@stricli/core` because it also needs `run`,
- * and the help command has no meaningful flags to capture.
+ * ```
+ * Correct:   import { buildCommand } from "../../lib/command.js";
+ * Incorrect: import { buildCommand } from "@stricli/core";         // skips everything!
+ * ```
  */
 
 import {
@@ -20,6 +31,12 @@ import {
   buildCommand as stricliCommand,
   numberParser as stricliNumberParser,
 } from "@stricli/core";
+import {
+  LOG_LEVEL_NAMES,
+  type LogLevelName,
+  parseLogLevel,
+  setLogLevel,
+} from "./logger.js";
 import { setArgsContext, setFlagContext } from "./telemetry.js";
 
 /**
@@ -54,23 +71,81 @@ type LocalCommandBuilderArguments<
   readonly func: CommandFunction<FLAGS, ARGS, CONTEXT>;
 };
 
+// ---------------------------------------------------------------------------
+// Global logging flags
+// ---------------------------------------------------------------------------
+
 /**
- * Build a command with automatic flag telemetry.
+ * Hidden `--log-level` flag injected into every command by {@link buildCommand}.
  *
- * This is a drop-in replacement for Stricli's buildCommand that wraps the
- * command function to automatically capture flag values as Sentry tags.
+ * Accepts one of the valid log level names. Hidden so it doesn't clutter
+ * individual command `--help` output — it's documented at the CLI level.
+ */
+export const LOG_LEVEL_FLAG = {
+  kind: "enum" as const,
+  values: LOG_LEVEL_NAMES as unknown as LogLevelName[],
+  brief: "Set log verbosity level",
+  optional: true as const,
+  hidden: true as const,
+} as const;
+
+/**
+ * Hidden `--verbose` flag injected into every command by {@link buildCommand}.
+ * Equivalent to `--log-level debug`.
+ */
+export const VERBOSE_FLAG = {
+  kind: "boolean" as const,
+  brief: "Enable verbose (debug-level) logging output",
+  default: false,
+  hidden: true as const,
+} as const;
+
+/** The flag key for the injected --log-level flag (always stripped) */
+const LOG_LEVEL_KEY = "log-level";
+
+/**
+ * Apply logging flags parsed by Stricli.
  *
- * Usage is identical to Stricli's buildCommand - just change the import:
- * ```ts
- * // Before:
- * import { buildCommand } from "@stricli/core";
+ * `--log-level` takes priority over `--verbose`. If neither is specified,
+ * the level is left as-is (env var or default).
  *
- * // After:
- * import { buildCommand } from "../../lib/command.js";
- * ```
+ * @param logLevel - Value of the `--log-level` flag, if provided
+ * @param verbose - Value of the `--verbose` flag
+ */
+export function applyLoggingFlags(
+  logLevel: LogLevelName | undefined,
+  verbose: boolean
+): void {
+  if (logLevel) {
+    setLogLevel(parseLogLevel(logLevel));
+  } else if (verbose) {
+    setLogLevel(parseLogLevel("debug"));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// buildCommand — the single entry point for all Sentry CLI commands
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a Sentry CLI command with telemetry and global logging flags.
+ *
+ * This is the **only** command builder that should be used. It:
+ * 1. Injects hidden `--log-level` and `--verbose` flags into the parameters
+ * 2. Intercepts them before the original `func` runs to call `setLogLevel()`
+ * 3. Strips injected flags so the original function never sees them
+ * 4. Captures flag values and positional arguments as Sentry telemetry context
+ *
+ * When a command already defines its own `verbose` flag (e.g. the `api` command
+ * uses `--verbose` for HTTP request/response output), the injected `VERBOSE_FLAG`
+ * is skipped. The command's own `verbose` value is still used for log-level
+ * side-effects, and it is **not** stripped — the original func receives it as usual.
  *
- * @param builderArgs - Same arguments as Stricli's buildCommand
- * @returns A Command with automatic flag telemetry
+ * Flag keys use kebab-case because Stricli uses the literal object key as
+ * the CLI flag name (e.g. `"log-level"` → `--log-level`).
+ *
+ * @param builderArgs - Same shape as Stricli's buildCommand arguments
+ * @returns A fully-wrapped Stricli Command
  */
 export function buildCommand<
   const FLAGS extends BaseFlags = NonNullable<unknown>,
@@ -81,27 +156,69 @@ export function buildCommand<
 ): Command<CONTEXT> {
   const originalFunc = builderArgs.func;
 
-  // Wrap the function to capture flags and args before execution
-  const wrappedFunc = function (
-    this: CONTEXT,
-    flags: FLAGS,
-    ...args: ARGS
-  ): ReturnType<typeof originalFunc> {
+  // Merge logging flags into the command's flag definitions.
+  // Quoted keys produce kebab-case CLI flags: "log-level" → --log-level
+  const existingParams = (builderArgs.parameters ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const existingFlags = (existingParams.flags ?? {}) as Record<string, unknown>;
+
+  // If the command already defines --verbose (e.g. api command), don't override it.
+  const commandOwnsVerbose = "verbose" in existingFlags;
+
+  const mergedFlags: Record<string, unknown> = {
+    ...existingFlags,
+    [LOG_LEVEL_KEY]: LOG_LEVEL_FLAG,
+  };
+  if (!commandOwnsVerbose) {
+    mergedFlags.verbose = VERBOSE_FLAG;
+  }
+  const mergedParams = { ...existingParams, flags: mergedFlags };
+
+  // Wrap func to intercept logging flags, capture telemetry, then call original
+  // biome-ignore lint/suspicious/noExplicitAny: Stricli's CommandFunction type is complex
+  const wrappedFunc = function (this: CONTEXT, flags: any, ...args: any[]) {
+    // Apply logging side-effects from whichever flags are present.
+    // The command's own --verbose (if any) also triggers debug-level logging.
+    const logLevel = flags[LOG_LEVEL_KEY] as LogLevelName | undefined;
+    const verbose = flags.verbose as boolean;
+    applyLoggingFlags(logLevel, verbose);
+
+    // Strip only the flags WE injected — never strip command-owned flags.
+    // --log-level is always ours. --verbose is only stripped when we injected it.
+    const cleanFlags: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(
+      flags as Record<string, unknown>
+    )) {
+      if (key === LOG_LEVEL_KEY) {
+        continue;
+      }
+      if (key === "verbose" && !commandOwnsVerbose) {
+        continue;
+      }
+      cleanFlags[key] = value;
+    }
+
     // Capture flag values as telemetry tags
-    setFlagContext(flags as Record<string, unknown>);
+    setFlagContext(cleanFlags);
 
     // Capture positional arguments as context
     if (args.length > 0) {
       setArgsContext(args);
     }
 
-    // Call the original function with the same context and arguments
-    return originalFunc.call(this, flags, ...args);
+    return originalFunc.call(
+      this,
+      cleanFlags as FLAGS,
+      ...(args as unknown as ARGS)
+    );
   } as typeof originalFunc;
 
-  // Build the command with the wrapped function
+  // Build the command with the wrapped function via Stricli
   return stricliCommand({
     ...builderArgs,
+    parameters: mergedParams,
     func: wrappedFunc,
     // biome-ignore lint/suspicious/noExplicitAny: Stricli types are complex unions
   } as any);