CLI-3 Add telemetry for CLI

Author: damien-urruty-sonarsource

docs/state-management.md

@@ -10,6 +10,7 @@ The state file persists configuration across CLI invocations and stores:
 - **Installed Hooks**: Pre/Post tool use and session start hooks for agent interactions
 - **Installed Skills**: Custom Claude Code skills
 - **Tool Metadata**: Installed external tools like sonar-secrets binary
+- **Telemetry data**: Anonymous usage statistics
 
 ## Location
 

spec.yaml

@@ -272,3 +272,26 @@ commands:
 
           - command: cat .env | sonar analyze secrets --stdin
             description: Scan stdin for hardcoded secrets
+
+  # Configure CLI
+  - name: config
+    description: Configure CLI settings
+    subcommands:
+      - name: telemetry
+        description: Configure telemetry settings
+        handler: ./src/commands/config.ts
+        options:
+          - name: enabled
+            type: boolean
+            description: Enable collection of anonymous usage statistics
+
+          - name: disabled
+            type: boolean
+            description: Disable collection of anonymous usage statistics
+
+        examples:
+          - command: sonar config telemetry --enabled
+            description: Enable collection of anonymous usage statistics
+
+          - command: sonar config telemetry --disabled
+            description: Disable collection of anonymous usage statistics

src/commands/auth.ts

@@ -35,6 +35,7 @@ import logger from '../lib/logger.js';
 import { warn, success, print, note, textPrompt, confirmPrompt } from '../ui/index.js';
 import { green, red, dim } from '../ui/colors.js';
 import { SONARCLOUD_URL, SONARCLOUD_HOSTNAME } from '../lib/config-constants.js';
+import {InvalidOptionError} from "./common/error";
 
 /**
  * Check if server is SonarCloud
@@ -184,6 +185,35 @@ async function validateOrSelectOrganization(
   return selectedOrg.trim();
 }
 
+async function validateLoginOptions(options: { server?: string; org?: string; withToken?: string; region?: string }) {
+  if (options.org !== undefined && !options.org.trim()) {
+    throw new InvalidOptionError('--org value cannot be empty. Provide a valid organization key (e.g., --org my-org)');
+  }
+
+  if (options.withToken !== undefined && !options.withToken.trim()) {
+    throw new InvalidOptionError('--with-token value cannot be empty. Provide a valid token or omit the flag for browser authentication');
+  }
+
+  if (options.server !== undefined && !options.server.trim()) {
+    throw new InvalidOptionError('--server value cannot be empty. Provide a valid URL (e.g., https://sonarcloud.io)');
+  }
+
+  let server = options.server;
+  if (!server) {
+    const configServer = await findServerInConfigs();
+    server = configServer || SONARCLOUD_URL;
+  }
+
+  if (options.server !== undefined) {
+    try {
+      new URL(server);
+    } catch {
+      throw new InvalidOptionError(`Invalid server URL: '${server}'. Provide a valid URL (e.g., https://sonarcloud.io)`);
+    }
+  }
+  return server;
+}
+
 /**
  * Login command - authenticate and save token with organization
  */
@@ -194,31 +224,7 @@ export async function authLoginCommand(options: {
   region?: string;
 }): Promise<void> {
   await runCommand(async () => {
-    if (options.org !== undefined && !options.org.trim()) {
-      throw new Error('--org value cannot be empty. Provide a valid organization key (e.g., --org my-org)');
-    }
-
-    if (options.withToken !== undefined && !options.withToken.trim()) {
-      throw new Error('--with-token value cannot be empty. Provide a valid token or omit the flag for browser authentication');
-    }
-
-    if (options.server !== undefined && !options.server.trim()) {
-      throw new Error('--server value cannot be empty. Provide a valid URL (e.g., https://sonarcloud.io)');
-    }
-
-    let server = options.server;
-    if (!server) {
-      const configServer = await findServerInConfigs();
-      server = configServer || SONARCLOUD_URL;
-    }
-
-    if (options.server !== undefined) {
-      try {
-        new URL(server);
-      } catch {
-        throw new Error(`Invalid server URL: '${server}'. Provide a valid URL (e.g., https://sonarcloud.io)`);
-      }
-    }
+    let server = await validateLoginOptions(options);
 
     const isCloud = isSonarCloud(server);
     const region = (options.region || 'eu') as 'eu' | 'us';
@@ -243,12 +249,25 @@ export async function authLoginCommand(options: {
     const state = loadState();
     const keystoreKey = generateConnectionId(server, org);
 
-    addOrUpdateConnection(state, server, isCloud ? 'cloud' : 'on-premise', {
+    const connection = addOrUpdateConnection(state, server, isCloud ? 'cloud' : 'on-premise', {
       orgKey: org,
       region: isCloud ? region : undefined,
       keystoreKey,
     });
 
+    // Fetch server-side IDs for telemetry enrichment (best effort, non-blocking on error).
+    const actualToken = token || (await getKeystoreToken(server, org));
+    if (actualToken) {
+      const apiClient = new SonarQubeClient(server, actualToken);
+      connection.userUuid = (await apiClient.getCurrentUser())?.id ?? null;
+      if (isCloud && org) {
+        connection.organizationUuidV4 = await apiClient.getOrganizationId(org);
+      } else if (!isCloud) {
+        const status = await apiClient.getSystemStatus();
+        connection.sqsInstallationId = status.id ?? null;
+      }
+    }
+
     saveState(state);
 
     const displayServer = isSonarCloud(server) ? `${server} (${org})` : server;

src/commands/common/error.ts

@@ -0,0 +1,39 @@
+/*
+ * SonarQube CLI
+ * Copyright (C) 2026 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+/**
+ * Thrown when the user provides invalid or conflicting command options.
+ */
+export class InvalidOptionError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = 'InvalidOptionError';
+  }
+}
+
+/**
+ * Thrown when the command (and options if any defined) are valid, but it failed to execute.
+ */
+export class CommandFailedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CommandFailedError';
+  }
+}

src/commands/config.ts

@@ -0,0 +1,43 @@
+/*
+ * SonarQube CLI
+ * Copyright (C) 2026 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+// Configure CLI settings
+
+import {loadState, saveState} from '../lib/state-manager.js';
+import {version as VERSION} from '../../package.json';
+import {success} from '../ui';
+import {InvalidOptionError} from './common/error.js';
+
+export interface ConfigureTelemetryOptions {
+  enabled?: boolean;
+  disabled?: boolean
+}
+
+export async function configureTelemetry(options: ConfigureTelemetryOptions): Promise<void> {
+  if (!options.enabled && !options.disabled) {
+    throw new InvalidOptionError('Either --enabled or --disabled is required');
+  }
+  if (options.enabled && options.disabled) {
+    throw new InvalidOptionError('Cannot use both --enabled and --disabled');
+  }
+  const state = loadState(VERSION);
+  state.telemetry.enabled = options.enabled ?? false;
+  saveState(state);
+  success(`Telemetry ${options.enabled ? 'enabled' : 'disabled'}.`);
+}

src/commands/secret-scan.ts

@@ -28,7 +28,8 @@ import { buildLocalBinaryName, detectPlatform } from '../lib/platform-detector.j
 import { getActiveConnection, loadState } from '../lib/state-manager.js';
 import { getToken } from '../lib/keychain.js';
 import logger from '../lib/logger.js';
-import { text, blank, success, error, print } from '../ui/index.js';
+import { text, blank, success, error, print } from '../ui';
+import { CommandFailedError, InvalidOptionError } from './common/error.js';
 
 const SCAN_TIMEOUT_MS = 30000;
 const STDIN_READ_TIMEOUT_MS = 5000;
@@ -78,13 +79,11 @@ async function setupScanEnvironment(options: { file?: string; stdin?: boolean })
 
 function validateScanOptions(options: { file?: string; stdin?: boolean }): void {
   if (!options.file && !options.stdin) {
-    error('Either --file or --stdin is required');
-    process.exit(1);
+    throw new InvalidOptionError('Either --file or --stdin is required');
   }
 
   if (options.file && options.stdin) {
-    error('Cannot use both --file and --stdin');
-    process.exit(1);
+    throw new InvalidOptionError('Cannot use both --file and --stdin');
   }
 }
 
@@ -103,15 +102,15 @@ async function setupAuth(): Promise<{ authUrl: string; authToken: string }> {
 
   if (!activeConnection) {
     logAuthConfigError();
-    process.exit(1);
+    throw new CommandFailedError('sonar-secrets authentication is not configured');
   }
 
   const authUrl = activeConnection.serverUrl;
   const authToken = await getToken(authUrl, activeConnection.orgKey);
 
   if (!authUrl || !authToken) {
     logAuthConfigError();
-    process.exit(1);
+    throw new CommandFailedError('sonar-secrets authentication is not configured');
   }
 
   return { authUrl, authToken };
@@ -142,13 +141,11 @@ async function performFileScan(
   scanStartTime: number
 ): Promise<void> {
   if (!file) {
-    error('File path is required');
-    process.exit(1);
+    throw new InvalidOptionError('File path is required');
   }
 
   if (!existsSync(file)) {
-    error(`File not found: ${file}`);
-    process.exit(1);
+    throw new InvalidOptionError(`File not found: ${file}`);
   }
 
   const result = await runScan(binaryPath, file, authUrl, authToken);
@@ -166,7 +163,7 @@ function validateCheckCommandEnvironment(binaryPath: string): void {
   if (!existsSync(binaryPath)) {
     error('sonar-secrets is not installed');
     text('  Install with: sonar secret install');
-    process.exit(1);
+    throw new CommandFailedError('sonar-secrets is not installed');
   }
 }
 
@@ -284,15 +281,13 @@ function handleScanSuccess(result: { stdout: string }, scanDurationMs: number):
     text(`  Duration: ${scanDurationMs}ms`);
     displayScanResults(scanResult);
     blank();
-    process.exit(0);
   } catch (parseError) {
     logger.debug(`Failed to parse JSON output: ${(parseError as Error).message}`);
     blank();
     success('Scan completed successfully');
     blank();
     print(result.stdout);
     blank();
-    process.exit(0);
   }
 }
 
@@ -345,10 +340,18 @@ function handleScanFailure(
   }
   blank();
   // Binary exit 1 = secrets found — remap to 51 so hooks can distinguish from generic errors
-  process.exit(exitCode === 1 ? SECRET_SCAN_POSITIVE_EXIT_CODE : exitCode);
+  process.exitCode = exitCode === 1 ? SECRET_SCAN_POSITIVE_EXIT_CODE : exitCode;
 }
 
 function handleScanError(err: unknown): void {
+  if (err instanceof InvalidOptionError) {
+    throw err;
+  }
+
+  if (err instanceof CommandFailedError) {
+    throw err;
+  }
+
   const errorMessage = (err as Error).message;
 
   blank();
@@ -364,5 +367,5 @@ function handleScanError(err: unknown): void {
   }
 
   blank();
-  process.exit(1);
+  throw new CommandFailedError(errorMessage);
 }