CLI-3 Add telemetry for CLI

Author: damien-urruty-sonarsource

README.md

@@ -268,6 +268,35 @@ Scan stdin for hardcoded secrets
 
 ---
 
+### `sonar config`
+
+Configure CLI settings
+
+#### `sonar config telemetry`
+
+Configure telemetry settings
+
+**Options:**
+
+| Option       | Type    | Required | Description                                      | Default |
+| ------------ | ------- | -------- | ------------------------------------------------ | ------- |
+| `--enabled`  | boolean | No       | Enable collection of anonymous usage statistics  | -       |
+| `--disabled` | boolean | No       | Disable collection of anonymous usage statistics | -       |
+
+**Examples:**
+
+```bash
+sonar config telemetry --enabled
+```
+Enable collection of anonymous usage statistics
+
+```bash
+sonar config telemetry --disabled
+```
+Disable collection of anonymous usage statistics
+
+---
+
 ## Option Types
 
 - `string` — text value (e.g. `--server https://sonarcloud.io`)

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

@@ -281,3 +281,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

@@ -40,6 +40,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
@@ -191,6 +192,48 @@ 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
  */
@@ -201,39 +244,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)`,
-        );
-      }
-    }
+    const server = await validateLoginOptions(options);
 
     const isCloud = isSonarCloud(server);
     const region = (options.region || 'eu') as 'eu' | 'us';
@@ -265,12 +276,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,45 @@
+/*
+ * 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 { info, success } from '../ui';
+import { InvalidOptionError } from './common/error.js';
+
+export interface ConfigureTelemetryOptions {
+  enabled?: boolean;
+  disabled?: boolean;
+}
+
+export function configureTelemetry(options: ConfigureTelemetryOptions): Promise<void> {
+  if (options.enabled && options.disabled) {
+    return Promise.reject(new InvalidOptionError('Cannot use both --enabled and --disabled'));
+  }
+  if (!options.enabled && !options.disabled) {
+    const state = loadState();
+    info(`Telemetry is currently ${state.telemetry.enabled ? 'enabled' : 'disabled'}.`);
+    return Promise.resolve();
+  }
+  const state = loadState();
+  state.telemetry.enabled = options.enabled ?? false;
+  saveState(state);
+  success(`Telemetry ${options.enabled ? 'enabled' : 'disabled'}.`);
+  return Promise.resolve();
+}

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;
@@ -75,13 +76,11 @@ async function setupScanEnvironment(options: {
 
 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');
   }
 }
 
@@ -100,15 +99,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 };
@@ -139,13 +138,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);
@@ -163,7 +160,7 @@ function validateCheckCommandEnvironment(binaryPath: string): void {
   if (!existsSync(binaryPath)) {
     error('sonar-secrets is not installed');
     text('  Install with: sonar install secrets');
-    process.exit(1);
+    throw new CommandFailedError('sonar-secrets is not installed');
   }
 }
 
@@ -271,15 +268,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);
   }
 }
 
@@ -332,10 +327,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();
@@ -355,5 +358,5 @@ function handleScanError(err: unknown): void {
   }
 
   blank();
-  process.exit(1);
+  throw new CommandFailedError(errorMessage);
 }