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 injected by a buildSentryCommand() wrapper:

- New `buildSentryCommand()` in src/lib/command.ts wraps buildCommand to
  inject hidden `--log-level` (enum) and `--verbose` (boolean) flags into
  every command. The wrapper intercepts them, applies setLogLevel(), then
  strips them before calling the original func.

- The `api` command keeps its own `--verbose` (HTTP semantics) and adds
  only `--log-level` via LOG_LEVEL_FLAG manually.

- 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,10 @@ 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.
+
+<!-- lore:019cbfaa-0001-7000-a000-000000000001 -->
+* **buildSentryCommand injects hidden --verbose and --log-level flags into every command**: Stricli has no global flags (bloomberg/stricli#106 closed as not planned). The fix: \`buildSentryCommand\` in \`src/lib/command.ts\` wraps Stricli's \`buildCommand\` to inject hidden \`--log-level\` (enum) and \`--verbose\` (boolean) flags into every command's parameters. The wrapper intercepts these flags before calling the original func, applies them via \`setLogLevel()\`, then strips them from the flags object. The \`api\` command uses \`buildCommand\` directly (not \`buildSentryCommand\`) because it has its own \`--verbose\` with HTTP semantics — it adds \`LOG\_LEVEL\_FLAG\` manually. 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
+  // buildSentryCommand 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/api.ts

@@ -7,8 +7,13 @@
 
 import type { SentryContext } from "../context.js";
 import { rawApiRequest } from "../lib/api-client.js";
-import { buildCommand } from "../lib/command.js";
+import {
+  applyLoggingFlags,
+  buildCommand,
+  LOG_LEVEL_FLAG,
+} from "../lib/command.js";
 import { ValidationError } from "../lib/errors.js";
+import type { LogLevelName } from "../lib/logger.js";
 import type { Writer } from "../types/index.js";
 
 type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
@@ -23,6 +28,7 @@ type ApiFlags = {
   readonly include: boolean;
   readonly silent: boolean;
   readonly verbose: boolean;
+  readonly "log-level"?: LogLevelName;
 };
 
 // Request Parsing
@@ -1085,6 +1091,7 @@ export const apiCommand = buildCommand({
         brief: "Include full HTTP request and response in the output",
         default: false,
       },
+      "log-level": LOG_LEVEL_FLAG,
     },
     aliases: {
       X: "method",
@@ -1102,6 +1109,10 @@ export const apiCommand = buildCommand({
   ): Promise<void> {
     const { stdout, stderr, stdin } = this;
 
+    // Apply logging flags. The api command's --verbose has its own HTTP
+    // semantics, but we also treat it as debug-level logging.
+    applyLoggingFlags(flags["log-level"], flags.verbose);
+
     // Normalize endpoint to ensure trailing slash (Sentry API requirement)
     const normalizedEndpoint = normalizeEndpoint(endpoint);
 

src/commands/auth/login.ts

@@ -1,6 +1,6 @@
 import type { SentryContext } from "../../context.js";
 import { getCurrentUser, getUserRegions } from "../../lib/api-client.js";
-import { buildCommand, numberParser } from "../../lib/command.js";
+import { buildSentryCommand, 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";
@@ -14,7 +14,7 @@ type LoginFlags = {
   readonly timeout: number;
 };
 
-export const loginCommand = buildCommand({
+export const loginCommand = buildSentryCommand({
   docs: {
     brief: "Authenticate with Sentry",
     fullDescription:

src/commands/auth/logout.ts

@@ -5,12 +5,12 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { buildCommand } from "../../lib/command.js";
+import { buildSentryCommand } 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";
 
-export const logoutCommand = buildCommand({
+export const logoutCommand = buildSentryCommand({
   docs: {
     brief: "Log out of Sentry",
     fullDescription:

src/commands/auth/refresh.ts

@@ -5,7 +5,7 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { buildCommand } from "../../lib/command.js";
+import { buildSentryCommand } 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";
@@ -24,7 +24,7 @@ type RefreshOutput = {
   expiresAt?: string;
 };
 
-export const refreshCommand = buildCommand({
+export const refreshCommand = buildSentryCommand({
   docs: {
     brief: "Refresh your authentication token",
     fullDescription: `

src/commands/auth/status.ts

@@ -6,7 +6,7 @@
 
 import type { SentryContext } from "../../context.js";
 import { listOrganizations } from "../../lib/api-client.js";
-import { buildCommand } from "../../lib/command.js";
+import { buildSentryCommand } from "../../lib/command.js";
 import {
   type AuthConfig,
   getAuthConfig,
@@ -117,7 +117,7 @@ async function verifyCredentials(
   }
 }
 
-export const statusCommand = buildCommand({
+export const statusCommand = buildSentryCommand({
   docs: {
     brief: "View authentication status",
     fullDescription:

src/commands/auth/token.ts

@@ -6,11 +6,11 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { buildCommand } from "../../lib/command.js";
+import { buildSentryCommand } from "../../lib/command.js";
 import { getAuthToken } from "../../lib/db/auth.js";
 import { AuthError } from "../../lib/errors.js";
 
-export const tokenCommand = buildCommand({
+export const tokenCommand = buildSentryCommand({
   docs: {
     brief: "Print the stored authentication token",
     fullDescription:

src/commands/auth/whoami.ts

@@ -8,7 +8,7 @@
 
 import type { SentryContext } from "../../context.js";
 import { getCurrentUser } from "../../lib/api-client.js";
-import { buildCommand } from "../../lib/command.js";
+import { buildSentryCommand } from "../../lib/command.js";
 import { isAuthenticated } from "../../lib/db/auth.js";
 import { setUserInfo } from "../../lib/db/user.js";
 import { AuthError } from "../../lib/errors.js";
@@ -18,7 +18,7 @@ type WhoamiFlags = {
   readonly json: boolean;
 };
 
-export const whoamiCommand = buildCommand({
+export const whoamiCommand = buildSentryCommand({
   docs: {
     brief: "Show the currently authenticated user",
     fullDescription: