workos 0.15.2 → 0.16.0

package/dist/utils/command-telemetry.js

@@ -0,0 +1,67 @@
+import { COMMAND_ALIASES } from '../lib/command-aliases.js';
+import { getTopLevelCommandNames } from './help-json.js';
+let knownTopLevelCommands = null;
+/** Canonical top-level command heads (registry + alias targets), memoized. */
+function topLevelCommands() {
+    if (!knownTopLevelCommands) {
+        const names = new Set(getTopLevelCommandNames());
+        // Alias targets resolve to a canonical head (e.g. claim -> env.claim -> env).
+        for (const target of Object.values(COMMAND_ALIASES)) {
+            names.add(target.split('.')[0]);
+        }
+        knownTopLevelCommands = names;
+    }
+    return knownTopLevelCommands;
+}
+export const SKIP_TELEMETRY_COMMANDS = new Set(['install', 'dashboard', 'root', 'telemetry']);
+export function resolveCanonicalName(parts) {
+    if (parts.length === 0)
+        return 'root';
+    const resolved = [...parts];
+    resolved[0] = COMMAND_ALIASES[resolved[0]] ?? resolved[0];
+    return resolved.join('.');
+}
+/**
+ * Resolve the command name from raw argv for paths where yargs validation
+ * fails before middleware runs (e.g. a missing required argument).
+ *
+ * Returns the first token that resolves to a KNOWN top-level command. Tokens
+ * are matched against the command registry rather than trusting position, so
+ * an option value preceding the command (e.g. `--api-key sk_live_… org` or
+ * `--mode ci org`) can never be recorded as the command name — that would leak
+ * secrets/values into telemetry and explode cardinality. Anything that isn't a
+ * known command (typos, stray values, `--help`) returns 'root', which is
+ * skipped. Only the top-level command is recorded; later positionals can be
+ * user values (org names, emails, IDs), so they are never included.
+ */
+export function resolveCommandNameFromRawArgs(rawArgs) {
+    const known = topLevelCommands();
+    for (const token of rawArgs) {
+        if (token.startsWith('-'))
+            continue;
+        const canonical = resolveCanonicalName([token]);
+        if (known.has(canonical.split('.')[0]))
+            return canonical;
+    }
+    return 'root';
+}
+export function extractUserFlags(rawArgs) {
+    const passedFlags = rawArgs
+        .filter((arg) => {
+        // `--` is the positional separator, not a flag.
+        if (arg === '--')
+            return false;
+        // Long flags: --name or --name=value (must start with a letter, so
+        // negative numbers like -1 / --1 are not mistaken for flags).
+        if (/^--[A-Za-z][\w-]*(=.*)?$/.test(arg))
+            return true;
+        // Short flags: a single letter, e.g. -v.
+        if (/^-[A-Za-z]$/.test(arg))
+            return true;
+        return false;
+    })
+        .map((arg) => arg.replace(/^-+/, '').split('=')[0])
+        .filter(Boolean);
+    return [...new Set(passedFlags)];
+}
+//# sourceMappingURL=command-telemetry.js.map

package/dist/utils/command-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-telemetry.js","sourceRoot":"","sources":["../../src/utils/command-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,IAAI,qBAAqB,GAAuB,IAAI,CAAC;AAErD,8EAA8E;AAC9E,SAAS,gBAAgB;IACvB,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,uBAAuB,EAAE,CAAC,CAAC;QACjD,8EAA8E;QAC9E,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,qBAAqB,GAAG,KAAK,CAAC;IAChC,CAAC;IACD,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAE9F,MAAM,UAAU,oBAAoB,CAAC,KAAe;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACtC,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC5B,QAAQ,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAiB;IAC7D,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACpC,MAAM,SAAS,GAAG,oBAAoB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAChD,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAiB;IAChD,MAAM,WAAW,GAAG,OAAO;SACxB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QACd,gDAAgD;QAChD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC/B,mEAAmE;QACnE,8DAA8D;QAC9D,IAAI,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,yCAAyC;QACzC,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;SAClD,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;AACnC,CAAC","sourcesContent":["import { COMMAND_ALIASES } from '../lib/command-aliases.js';\nimport { getTopLevelCommandNames } from './help-json.js';\n\nlet knownTopLevelCommands: Set<string> | null = null;\n\n/** Canonical top-level command heads (registry + alias targets), memoized. */\nfunction topLevelCommands(): Set<string> {\n  if (!knownTopLevelCommands) {\n    const names = new Set(getTopLevelCommandNames());\n    // Alias targets resolve to a canonical head (e.g. claim -> env.claim -> env).\n    for (const target of Object.values(COMMAND_ALIASES)) {\n      names.add(target.split('.')[0]);\n    }\n    knownTopLevelCommands = names;\n  }\n  return knownTopLevelCommands;\n}\n\nexport const SKIP_TELEMETRY_COMMANDS = new Set(['install', 'dashboard', 'root', 'telemetry']);\n\nexport function resolveCanonicalName(parts: string[]): string {\n  if (parts.length === 0) return 'root';\n  const resolved = [...parts];\n  resolved[0] = COMMAND_ALIASES[resolved[0]] ?? resolved[0];\n  return resolved.join('.');\n}\n\n/**\n * Resolve the command name from raw argv for paths where yargs validation\n * fails before middleware runs (e.g. a missing required argument).\n *\n * Returns the first token that resolves to a KNOWN top-level command. Tokens\n * are matched against the command registry rather than trusting position, so\n * an option value preceding the command (e.g. `--api-key sk_live_… org` or\n * `--mode ci org`) can never be recorded as the command name — that would leak\n * secrets/values into telemetry and explode cardinality. Anything that isn't a\n * known command (typos, stray values, `--help`) returns 'root', which is\n * skipped. Only the top-level command is recorded; later positionals can be\n * user values (org names, emails, IDs), so they are never included.\n */\nexport function resolveCommandNameFromRawArgs(rawArgs: string[]): string {\n  const known = topLevelCommands();\n  for (const token of rawArgs) {\n    if (token.startsWith('-')) continue;\n    const canonical = resolveCanonicalName([token]);\n    if (known.has(canonical.split('.')[0])) return canonical;\n  }\n  return 'root';\n}\n\nexport function extractUserFlags(rawArgs: string[]): string[] {\n  const passedFlags = rawArgs\n    .filter((arg) => {\n      // `--` is the positional separator, not a flag.\n      if (arg === '--') return false;\n      // Long flags: --name or --name=value (must start with a letter, so\n      // negative numbers like -1 / --1 are not mistaken for flags).\n      if (/^--[A-Za-z][\\w-]*(=.*)?$/.test(arg)) return true;\n      // Short flags: a single letter, e.g. -v.\n      if (/^-[A-Za-z]$/.test(arg)) return true;\n      return false;\n    })\n    .map((arg) => arg.replace(/^-+/, '').split('=')[0])\n    .filter(Boolean);\n  return [...new Set(passedFlags)];\n}\n"]}

package/dist/utils/crash-reporter.d.ts

@@ -0,0 +1,13 @@
+/** Sanitize stack trace for telemetry: homedir, absolute-path collapse, secrets, truncation. */
+export declare function sanitizeStack(stack: string | undefined): string;
+/** Sanitize an error message for telemetry (homedir, secrets, truncation). */
+export declare function sanitizeMessage(msg: string | undefined): string;
+/**
+ * Register global handlers for uncaughtException and unhandledRejection
+ * that capture crash details before the process exits.
+ *
+ * Handlers are SYNCHRONOUS. Node does NOT await async uncaughtException handlers.
+ * We queue the event synchronously; store-forward's process.on('exit') handler
+ * persists it to disk. The next CLI invocation recovers and sends.
+ */
+export declare function installCrashReporter(): void;

package/dist/utils/crash-reporter.js

@@ -0,0 +1,91 @@
+import { analytics } from './analytics.js';
+import { CliExit } from './cli-exit.js';
+import { homedir } from 'node:os';
+// Hard ceiling the telemetry API enforces on every attribute value
+// (z.string().max(4096) in llm-gateway/types/telemetry-event.ts). The final
+// sanitized string — truncation marker included — MUST stay within this, or
+// the whole crash event fails Zod validation server-side and is silently
+// dropped. Reserve room for the marker so a truncated stack lands at exactly
+// MAX_STACK_LENGTH rather than overshooting it.
+const MAX_STACK_LENGTH = 4096;
+const STACK_TRUNCATION_MARKER = '\n...[truncated]';
+const MAX_MESSAGE_LENGTH = 1024;
+const HOME = homedir();
+let isCrashing = false;
+/**
+ * Redact known credential patterns (Bearer tokens, sk_test_/sk_live_ keys,
+ * raw JWTs). Shared by sanitizeStack and sanitizeMessage because Node echoes
+ * `.message` into the leading `Error.stack` line, so secrets in messages also
+ * surface in stacks.
+ */
+function redactSecrets(s) {
+    return s
+        .replace(/Bearer\s+[A-Za-z0-9._-]+/g, 'Bearer <redacted>')
+        .replace(/\bsk_(test|live)_[A-Za-z0-9]+/g, 'sk_<redacted>')
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '<jwt-redacted>');
+}
+/** Sanitize stack trace for telemetry: homedir, absolute-path collapse, secrets, truncation. */
+export function sanitizeStack(stack) {
+    if (!stack)
+        return '';
+    let sanitized = stack.replaceAll(HOME, '~');
+    // Collapse absolute paths to their leaf segment. POSIX and Windows separately —
+    // Windows paths (C:\...\node_modules\) bypass the POSIX regex and would
+    // otherwise leak full local filesystem paths into telemetry.
+    sanitized = sanitized
+        .replace(/\/[^\s:]+\/(node_modules|dist|src)\//g, '$1/')
+        .replace(/[A-Za-z]:\\[^\s:]+\\(node_modules|dist|src)\\/g, '$1\\');
+    sanitized = redactSecrets(sanitized);
+    return sanitized.length > MAX_STACK_LENGTH
+        ? sanitized.slice(0, MAX_STACK_LENGTH - STACK_TRUNCATION_MARKER.length) + STACK_TRUNCATION_MARKER
+        : sanitized;
+}
+/** Sanitize an error message for telemetry (homedir, secrets, truncation). */
+export function sanitizeMessage(msg) {
+    if (!msg)
+        return '';
+    const sanitized = redactSecrets(msg.replaceAll(HOME, '~'));
+    return sanitized.length > MAX_MESSAGE_LENGTH ? sanitized.slice(0, MAX_MESSAGE_LENGTH) + '...[truncated]' : sanitized;
+}
+/**
+ * Register global handlers for uncaughtException and unhandledRejection
+ * that capture crash details before the process exits.
+ *
+ * Handlers are SYNCHRONOUS. Node does NOT await async uncaughtException handlers.
+ * We queue the event synchronously; store-forward's process.on('exit') handler
+ * persists it to disk. The next CLI invocation recovers and sends.
+ */
+export function installCrashReporter() {
+    process.on('uncaughtException', (error) => {
+        // A CliExit that reaches here escaped the normal lifecycle (e.g. thrown
+        // from a fire-and-forget async event listener like `child.on('error')` in
+        // dev.ts). It is an intentional exit, NOT a crash — record no crash event,
+        // just honor the requested code.
+        if (error instanceof CliExit) {
+            process.exit(error.exitCode);
+        }
+        reportCrashSync(error);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        if (reason instanceof CliExit) {
+            process.exit(reason.exitCode);
+        }
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        reportCrashSync(error);
+        process.exit(1);
+    });
+}
+function reportCrashSync(error) {
+    if (isCrashing)
+        return;
+    isCrashing = true;
+    try {
+        // captureUnhandledCrash sanitizes both message and stack at the analytics boundary.
+        analytics.captureUnhandledCrash(error);
+    }
+    catch {
+        // Telemetry must never prevent exit
+    }
+}
+//# sourceMappingURL=crash-reporter.js.map

package/dist/utils/crash-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-reporter.js","sourceRoot":"","sources":["../../src/utils/crash-reporter.ts"],"names":[],"mappings":"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","sourcesContent":["import { analytics } from './analytics.js';\nimport { CliExit } from './cli-exit.js';\nimport { homedir } from 'node:os';\n\n// Hard ceiling the telemetry API enforces on every attribute value\n// (z.string().max(4096) in llm-gateway/types/telemetry-event.ts). The final\n// sanitized string — truncation marker included — MUST stay within this, or\n// the whole crash event fails Zod validation server-side and is silently\n// dropped. Reserve room for the marker so a truncated stack lands at exactly\n// MAX_STACK_LENGTH rather than overshooting it.\nconst MAX_STACK_LENGTH = 4096;\nconst STACK_TRUNCATION_MARKER = '\\n...[truncated]';\nconst MAX_MESSAGE_LENGTH = 1024;\nconst HOME = homedir();\nlet isCrashing = false;\n\n/**\n * Redact known credential patterns (Bearer tokens, sk_test_/sk_live_ keys,\n * raw JWTs). Shared by sanitizeStack and sanitizeMessage because Node echoes\n * `.message` into the leading `Error.stack` line, so secrets in messages also\n * surface in stacks.\n */\nfunction redactSecrets(s: string): string {\n  return s\n    .replace(/Bearer\\s+[A-Za-z0-9._-]+/g, 'Bearer <redacted>')\n    .replace(/\\bsk_(test|live)_[A-Za-z0-9]+/g, 'sk_<redacted>')\n    .replace(/\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+/g, '<jwt-redacted>');\n}\n\n/** Sanitize stack trace for telemetry: homedir, absolute-path collapse, secrets, truncation. */\nexport function sanitizeStack(stack: string | undefined): string {\n  if (!stack) return '';\n  let sanitized = stack.replaceAll(HOME, '~');\n  // Collapse absolute paths to their leaf segment. POSIX and Windows separately —\n  // Windows paths (C:\\...\\node_modules\\) bypass the POSIX regex and would\n  // otherwise leak full local filesystem paths into telemetry.\n  sanitized = sanitized\n    .replace(/\\/[^\\s:]+\\/(node_modules|dist|src)\\//g, '$1/')\n    .replace(/[A-Za-z]:\\\\[^\\s:]+\\\\(node_modules|dist|src)\\\\/g, '$1\\\\');\n  sanitized = redactSecrets(sanitized);\n  return sanitized.length > MAX_STACK_LENGTH\n    ? sanitized.slice(0, MAX_STACK_LENGTH - STACK_TRUNCATION_MARKER.length) + STACK_TRUNCATION_MARKER\n    : sanitized;\n}\n\n/** Sanitize an error message for telemetry (homedir, secrets, truncation). */\nexport function sanitizeMessage(msg: string | undefined): string {\n  if (!msg) return '';\n  const sanitized = redactSecrets(msg.replaceAll(HOME, '~'));\n  return sanitized.length > MAX_MESSAGE_LENGTH ? sanitized.slice(0, MAX_MESSAGE_LENGTH) + '...[truncated]' : sanitized;\n}\n\n/**\n * Register global handlers for uncaughtException and unhandledRejection\n * that capture crash details before the process exits.\n *\n * Handlers are SYNCHRONOUS. Node does NOT await async uncaughtException handlers.\n * We queue the event synchronously; store-forward's process.on('exit') handler\n * persists it to disk. The next CLI invocation recovers and sends.\n */\nexport function installCrashReporter(): void {\n  process.on('uncaughtException', (error) => {\n    // A CliExit that reaches here escaped the normal lifecycle (e.g. thrown\n    // from a fire-and-forget async event listener like `child.on('error')` in\n    // dev.ts). It is an intentional exit, NOT a crash — record no crash event,\n    // just honor the requested code.\n    if (error instanceof CliExit) {\n      process.exit(error.exitCode);\n    }\n    reportCrashSync(error);\n    process.exit(1);\n  });\n\n  process.on('unhandledRejection', (reason) => {\n    if (reason instanceof CliExit) {\n      process.exit(reason.exitCode);\n    }\n    const error = reason instanceof Error ? reason : new Error(String(reason));\n    reportCrashSync(error);\n    process.exit(1);\n  });\n}\n\nfunction reportCrashSync(error: Error): void {\n  if (isCrashing) return;\n  isCrashing = true;\n  try {\n    // captureUnhandledCrash sanitizes both message and stack at the analytics boundary.\n    analytics.captureUnhandledCrash(error);\n  } catch {\n    // Telemetry must never prevent exit\n  }\n}\n"]}

package/dist/utils/debug.d.ts

@@ -5,4 +5,5 @@ export declare function logWarn(...args: unknown[]): void;
 export declare function logVisibleWarn(...args: unknown[]): void;
 export declare function logError(...args: unknown[]): void;
 export declare function debug(...args: unknown[]): void;
+export declare function isDebugEnabled(): boolean;
 export declare function enableDebugLogs(): void;

package/dist/utils/debug.js

@@ -91,11 +91,14 @@ export function logError(...args) {
     writeLog('ERROR', '❌', args);
 }
 export function debug(...args) {
-    if (!debugEnabled || isJsonMode())
+    if (!isDebugEnabled())
         return;
     const msg = args.map((a) => prepareMessage(a)).join(' ');
     clack.log.info(chalk.dim(msg));
 }
+export function isDebugEnabled() {
+    return debugEnabled && !isJsonMode();
+}
 export function enableDebugLogs() {
     debugEnabled = true;
 }

package/dist/utils/debug.js.map

@@ -1 +1 @@
-{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"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","sourcesContent":["import { appendFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } from 'os';\nimport chalk from 'chalk';\nimport { prepareMessage } from './logging.js';\nimport { redactCredentials } from './redact.js';\nimport clack from './clack.js';\nimport { isJsonMode } from './output.js';\n\nlet debugEnabled = false;\nlet sessionLogPath: string | null = null;\n\nconst LOG_DIR = join(homedir(), '.workos', 'logs');\nconst MAX_LOG_FILES = 10;\n\nfunction ensureLogDir(): string {\n  if (!existsSync(LOG_DIR)) {\n    mkdirSync(LOG_DIR, { recursive: true });\n  }\n  return LOG_DIR;\n}\n\nfunction getSafeTimestamp(): string {\n  return new Date().toISOString().replace(/:/g, '-');\n}\n\nfunction rotateLogFiles(): void {\n  try {\n    const dir = ensureLogDir();\n    const files = readdirSync(dir)\n      .filter((f) => f.startsWith('workos-') && f.endsWith('.log'))\n      .sort();\n\n    const toDelete = files.slice(0, Math.max(0, files.length - MAX_LOG_FILES + 1));\n    for (const file of toDelete) {\n      try {\n        unlinkSync(join(dir, file));\n      } catch {\n        // Ignore deletion failures\n      }\n    }\n  } catch {\n    // Ignore rotation failures\n  }\n}\n\nexport function initLogFile(): void {\n  try {\n    rotateLogFiles();\n    const dir = ensureLogDir();\n    const timestamp = getSafeTimestamp();\n    sessionLogPath = join(dir, `workos-${timestamp}.log`);\n\n    const header = `${'='.repeat(60)}\\nWorkOS AuthKit Installer Run: ${new Date().toISOString()}\\n${'='.repeat(60)}\\n`;\n    appendFileSync(sessionLogPath, header);\n  } catch {\n    sessionLogPath = null;\n  }\n}\n\nexport function getLogFilePath(): string | null {\n  return sessionLogPath;\n}\n\nfunction writeLog(level: 'INFO' | 'WARN' | 'ERROR', emoji: string, args: unknown[]): string {\n  const redactedArgs = args.map((a) => (typeof a === 'object' && a !== null ? redactCredentials(a) : a));\n  const msg = redactedArgs.map((a) => prepareMessage(a)).join(' ');\n\n  // Write to console if debug enabled\n  if (debugEnabled && !isJsonMode()) {\n    const color = level === 'ERROR' ? chalk.red : level === 'WARN' ? chalk.yellow : chalk.dim;\n    clack.log.info(color(`${emoji} ${msg}`));\n  }\n\n  // Write to log file\n  if (sessionLogPath) {\n    try {\n      const timestamp = new Date().toISOString();\n      appendFileSync(sessionLogPath, `[${timestamp}] ${emoji} ${level}: ${msg}\\n`);\n    } catch {\n      // Ignore write failures\n    }\n  }\n\n  return msg;\n}\n\nexport function logInfo(...args: unknown[]): void {\n  writeLog('INFO', 'ℹ️ ', args);\n}\n\nexport function logWarn(...args: unknown[]): void {\n  writeLog('WARN', '⚠️ ', args);\n}\n\nexport function logVisibleWarn(...args: unknown[]): void {\n  const msg = writeLog('WARN', '⚠️ ', args);\n  if (!debugEnabled && !isJsonMode()) {\n    console.error(chalk.yellow(`⚠️  ${msg}`));\n  }\n}\n\nexport function logError(...args: unknown[]): void {\n  writeLog('ERROR', '❌', args);\n}\n\nexport function debug(...args: unknown[]): void {\n  if (!debugEnabled || isJsonMode()) return;\n  const msg = args.map((a) => prepareMessage(a)).join(' ');\n  clack.log.info(chalk.dim(msg));\n}\n\nexport function enableDebugLogs(): void {\n  debugEnabled = true;\n}\n"]}
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"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","sourcesContent":["import { appendFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'fs';\nimport { join } from 'path';\nimport { homedir } from 'os';\nimport chalk from 'chalk';\nimport { prepareMessage } from './logging.js';\nimport { redactCredentials } from './redact.js';\nimport clack from './clack.js';\nimport { isJsonMode } from './output.js';\n\nlet debugEnabled = false;\nlet sessionLogPath: string | null = null;\n\nconst LOG_DIR = join(homedir(), '.workos', 'logs');\nconst MAX_LOG_FILES = 10;\n\nfunction ensureLogDir(): string {\n  if (!existsSync(LOG_DIR)) {\n    mkdirSync(LOG_DIR, { recursive: true });\n  }\n  return LOG_DIR;\n}\n\nfunction getSafeTimestamp(): string {\n  return new Date().toISOString().replace(/:/g, '-');\n}\n\nfunction rotateLogFiles(): void {\n  try {\n    const dir = ensureLogDir();\n    const files = readdirSync(dir)\n      .filter((f) => f.startsWith('workos-') && f.endsWith('.log'))\n      .sort();\n\n    const toDelete = files.slice(0, Math.max(0, files.length - MAX_LOG_FILES + 1));\n    for (const file of toDelete) {\n      try {\n        unlinkSync(join(dir, file));\n      } catch {\n        // Ignore deletion failures\n      }\n    }\n  } catch {\n    // Ignore rotation failures\n  }\n}\n\nexport function initLogFile(): void {\n  try {\n    rotateLogFiles();\n    const dir = ensureLogDir();\n    const timestamp = getSafeTimestamp();\n    sessionLogPath = join(dir, `workos-${timestamp}.log`);\n\n    const header = `${'='.repeat(60)}\\nWorkOS AuthKit Installer Run: ${new Date().toISOString()}\\n${'='.repeat(60)}\\n`;\n    appendFileSync(sessionLogPath, header);\n  } catch {\n    sessionLogPath = null;\n  }\n}\n\nexport function getLogFilePath(): string | null {\n  return sessionLogPath;\n}\n\nfunction writeLog(level: 'INFO' | 'WARN' | 'ERROR', emoji: string, args: unknown[]): string {\n  const redactedArgs = args.map((a) => (typeof a === 'object' && a !== null ? redactCredentials(a) : a));\n  const msg = redactedArgs.map((a) => prepareMessage(a)).join(' ');\n\n  // Write to console if debug enabled\n  if (debugEnabled && !isJsonMode()) {\n    const color = level === 'ERROR' ? chalk.red : level === 'WARN' ? chalk.yellow : chalk.dim;\n    clack.log.info(color(`${emoji} ${msg}`));\n  }\n\n  // Write to log file\n  if (sessionLogPath) {\n    try {\n      const timestamp = new Date().toISOString();\n      appendFileSync(sessionLogPath, `[${timestamp}] ${emoji} ${level}: ${msg}\\n`);\n    } catch {\n      // Ignore write failures\n    }\n  }\n\n  return msg;\n}\n\nexport function logInfo(...args: unknown[]): void {\n  writeLog('INFO', 'ℹ️ ', args);\n}\n\nexport function logWarn(...args: unknown[]): void {\n  writeLog('WARN', '⚠️ ', args);\n}\n\nexport function logVisibleWarn(...args: unknown[]): void {\n  const msg = writeLog('WARN', '⚠️ ', args);\n  if (!debugEnabled && !isJsonMode()) {\n    console.error(chalk.yellow(`⚠️  ${msg}`));\n  }\n}\n\nexport function logError(...args: unknown[]): void {\n  writeLog('ERROR', '❌', args);\n}\n\nexport function debug(...args: unknown[]): void {\n  if (!isDebugEnabled()) return;\n  const msg = args.map((a) => prepareMessage(a)).join(' ');\n  clack.log.info(chalk.dim(msg));\n}\n\nexport function isDebugEnabled(): boolean {\n  return debugEnabled && !isJsonMode();\n}\n\nexport function enableDebugLogs(): void {\n  debugEnabled = true;\n}\n"]}

package/dist/utils/exit-codes.d.ts

@@ -7,6 +7,7 @@
  * 4 = Authentication required
  */
 import { type StructuredError } from './output.js';
+import type { TerminationReason } from './telemetry-types.js';
 export declare const ExitCode: {
     readonly SUCCESS: 0;
     readonly GENERAL_ERROR: 1;
@@ -14,6 +15,10 @@ export declare const ExitCode: {
     readonly AUTH_REQUIRED: 4;
 };
 export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+export declare function resolveErrorCode(code: string): {
+    reason: TerminationReason;
+    exit: ExitCodeValue;
+};
 /** Exit with a specific code, optionally writing a structured error first. */
 export declare function exitWithCode(code: ExitCodeValue, error?: StructuredError): never;
 /**

package/dist/utils/exit-codes.js

@@ -6,6 +6,7 @@
  * 2 = Cancelled (e.g., Ctrl+C, user cancelled prompt)
  * 4 = Authentication required
  */
+import { CliExit } from './cli-exit.js';
 import { outputError } from './output.js';
 import { formatWorkOSCommand } from './command-invocation.js';
 import { authLoginRecovery } from './recovery-hints.js';
@@ -16,12 +17,40 @@ export const ExitCode = {
     CANCELLED: 2,
     AUTH_REQUIRED: 4,
 };
+const ERROR_CODE_MAP = {
+    auth_required: { reason: 'auth_required', exit: ExitCode.AUTH_REQUIRED },
+    // resolveApiKey() emits `no_api_key` when no key is configured; semantically
+    // an auth failure, so it must not fall through to `validation_error`.
+    no_api_key: { reason: 'auth_required', exit: ExitCode.AUTH_REQUIRED },
+    cancelled: { reason: 'cancelled', exit: ExitCode.CANCELLED },
+};
+export function resolveErrorCode(code) {
+    const mapped = ERROR_CODE_MAP[code];
+    if (mapped)
+        return mapped;
+    if (code.startsWith('http_')) {
+        return { reason: 'api_error', exit: ExitCode.GENERAL_ERROR };
+    }
+    return { reason: 'validation_error', exit: ExitCode.GENERAL_ERROR };
+}
+function reasonForExitCode(code) {
+    if (code === ExitCode.AUTH_REQUIRED)
+        return 'auth_required';
+    if (code === ExitCode.CANCELLED)
+        return 'cancelled';
+    if (code === ExitCode.SUCCESS)
+        return 'success';
+    return 'validation_error';
+}
 /** Exit with a specific code, optionally writing a structured error first. */
 export function exitWithCode(code, error) {
     if (error) {
         outputError(error);
     }
-    process.exit(code);
+    throw new CliExit(code, {
+        reason: reasonForExitCode(code),
+        errorCode: error?.code,
+    });
 }
 /**
  * Convenience: exit with code 4 and auth-required error.

package/dist/utils/exit-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../src/utils/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAAC;IACV,aAAa,EAAE,CAAC;IAChB,SAAS,EAAE,CAAC;IACZ,aAAa,EAAE,CAAC;CACR,CAAC;AAIX,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,KAAuB;IACvE,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB,EAAE,OAAoD;IACzG,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC,IAAI,CAAC;IACvC,YAAY,CAAC,QAAQ,CAAC,aAAa,EAAE;QACnC,IAAI,EAAE,eAAe;QACrB,OAAO,EACL,OAAO;YACP,4BAA4B,mBAAmB,CAAC,YAAY,CAAC,uDAAuD;QACtH,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC;KAC3D,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Standardized exit codes following gh CLI convention.\n *\n * 0 = Success\n * 1 = General error\n * 2 = Cancelled (e.g., Ctrl+C, user cancelled prompt)\n * 4 = Authentication required\n */\n\nimport { outputError, type StructuredError } from './output.js';\nimport { formatWorkOSCommand } from './command-invocation.js';\nimport { authLoginRecovery } from './recovery-hints.js';\nimport { getInteractionMode } from './interaction-mode.js';\n\nexport const ExitCode = {\n  SUCCESS: 0,\n  GENERAL_ERROR: 1,\n  CANCELLED: 2,\n  AUTH_REQUIRED: 4,\n} as const;\n\nexport type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];\n\n/** Exit with a specific code, optionally writing a structured error first. */\nexport function exitWithCode(code: ExitCodeValue, error?: StructuredError): never {\n  if (error) {\n    outputError(error);\n  }\n  process.exit(code);\n}\n\n/**\n * Convenience: exit with code 4 and auth-required error.\n *\n * Recovery hints are inferred from interaction mode unless explicitly provided.\n */\nexport function exitWithAuthRequired(message?: string, options?: { recovery?: StructuredError['recovery'] }): never {\n  const mode = getInteractionMode().mode;\n  exitWithCode(ExitCode.AUTH_REQUIRED, {\n    code: 'auth_required',\n    message:\n      message ??\n      `Not authenticated. Run \\`${formatWorkOSCommand('auth login')}\\` in an interactive terminal, or set WORKOS_API_KEY.`,\n    recovery: options?.recovery ?? authLoginRecovery({ mode }),\n  });\n}\n"]}
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../../src/utils/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAAC;IACV,aAAa,EAAE,CAAC;IAChB,SAAS,EAAE,CAAC;IACZ,aAAa,EAAE,CAAC;CACR,CAAC;AAIX,MAAM,cAAc,GAAuE;IACzF,aAAa,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,EAAE;IACxE,6EAA6E;IAC7E,sEAAsE;IACtE,UAAU,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,EAAE;IACrE,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,EAAE;CAC7D,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAI3C,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,EAAE,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,EAAE,CAAC;AACtE,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAmB;IAC5C,IAAI,IAAI,KAAK,QAAQ,CAAC,aAAa;QAAE,OAAO,eAAe,CAAC;IAC5D,IAAI,IAAI,KAAK,QAAQ,CAAC,SAAS;QAAE,OAAO,WAAW,CAAC;IACpD,IAAI,IAAI,KAAK,QAAQ,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAChD,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,KAAuB;IACvE,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,IAAI,OAAO,CAAC,IAAI,EAAE;QACtB,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC;QAC/B,SAAS,EAAE,KAAK,EAAE,IAAI;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB,EAAE,OAAoD;IACzG,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC,IAAI,CAAC;IACvC,YAAY,CAAC,QAAQ,CAAC,aAAa,EAAE;QACnC,IAAI,EAAE,eAAe;QACrB,OAAO,EACL,OAAO;YACP,4BAA4B,mBAAmB,CAAC,YAAY,CAAC,uDAAuD;QACtH,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC;KAC3D,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Standardized exit codes following gh CLI convention.\n *\n * 0 = Success\n * 1 = General error\n * 2 = Cancelled (e.g., Ctrl+C, user cancelled prompt)\n * 4 = Authentication required\n */\n\nimport { CliExit } from './cli-exit.js';\nimport { outputError, type StructuredError } from './output.js';\nimport { formatWorkOSCommand } from './command-invocation.js';\nimport { authLoginRecovery } from './recovery-hints.js';\nimport { getInteractionMode } from './interaction-mode.js';\nimport type { TerminationReason } from './telemetry-types.js';\n\nexport const ExitCode = {\n  SUCCESS: 0,\n  GENERAL_ERROR: 1,\n  CANCELLED: 2,\n  AUTH_REQUIRED: 4,\n} as const;\n\nexport type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];\n\nconst ERROR_CODE_MAP: Record<string, { reason: TerminationReason; exit: ExitCodeValue }> = {\n  auth_required: { reason: 'auth_required', exit: ExitCode.AUTH_REQUIRED },\n  // resolveApiKey() emits `no_api_key` when no key is configured; semantically\n  // an auth failure, so it must not fall through to `validation_error`.\n  no_api_key: { reason: 'auth_required', exit: ExitCode.AUTH_REQUIRED },\n  cancelled: { reason: 'cancelled', exit: ExitCode.CANCELLED },\n};\n\nexport function resolveErrorCode(code: string): {\n  reason: TerminationReason;\n  exit: ExitCodeValue;\n} {\n  const mapped = ERROR_CODE_MAP[code];\n  if (mapped) return mapped;\n  if (code.startsWith('http_')) {\n    return { reason: 'api_error', exit: ExitCode.GENERAL_ERROR };\n  }\n  return { reason: 'validation_error', exit: ExitCode.GENERAL_ERROR };\n}\n\nfunction reasonForExitCode(code: ExitCodeValue): TerminationReason {\n  if (code === ExitCode.AUTH_REQUIRED) return 'auth_required';\n  if (code === ExitCode.CANCELLED) return 'cancelled';\n  if (code === ExitCode.SUCCESS) return 'success';\n  return 'validation_error';\n}\n\n/** Exit with a specific code, optionally writing a structured error first. */\nexport function exitWithCode(code: ExitCodeValue, error?: StructuredError): never {\n  if (error) {\n    outputError(error);\n  }\n  throw new CliExit(code, {\n    reason: reasonForExitCode(code),\n    errorCode: error?.code,\n  });\n}\n\n/**\n * Convenience: exit with code 4 and auth-required error.\n *\n * Recovery hints are inferred from interaction mode unless explicitly provided.\n */\nexport function exitWithAuthRequired(message?: string, options?: { recovery?: StructuredError['recovery'] }): never {\n  const mode = getInteractionMode().mode;\n  exitWithCode(ExitCode.AUTH_REQUIRED, {\n    code: 'auth_required',\n    message:\n      message ??\n      `Not authenticated. Run \\`${formatWorkOSCommand('auth login')}\\` in an interactive terminal, or set WORKOS_API_KEY.`,\n    recovery: options?.recovery ?? authLoginRecovery({ mode }),\n  });\n}\n"]}

package/dist/utils/help-json.d.ts

@@ -49,4 +49,10 @@ export declare function extractHelpJsonCommand(argv: string[]): string | undefin
  * @param subcommand - Optional command name to return a subtree for (e.g. "env").
  *                     Returns full tree if omitted or if command not found.
  */
+/**
+ * Top-level command names (first token of each registered command). Used by
+ * telemetry to recognise real commands without trusting arbitrary argv tokens
+ * (so option values / secrets are never recorded as a command name).
+ */
+export declare function getTopLevelCommandNames(): string[];
 export declare function buildCommandTree(subcommand?: string): HelpOutput | CommandSchema;

package/dist/utils/help-json.js

@@ -6,6 +6,7 @@
  * so we maintain a parallel typed registry.
  */
 import { getVersion } from '../lib/settings.js';
+import { COMMAND_ALIASES } from '../lib/command-aliases.js';
 // ---------------------------------------------------------------------------
 // Shared option fragments (mirrors bin.ts shared option objects)
 // ---------------------------------------------------------------------------
@@ -68,6 +69,15 @@ const commands = [
         description: 'Show current authentication status',
         options: [insecureStorageOpt],
     },
+    {
+        name: 'telemetry',
+        description: 'Manage telemetry collection (opt-out, opt-in, status)',
+        commands: [
+            { name: 'opt-out', description: 'Disable telemetry collection (persists across runs)' },
+            { name: 'opt-in', description: 'Re-enable telemetry collection' },
+            { name: 'status', description: 'Show whether telemetry is enabled and why' },
+        ],
+    },
     {
         name: 'skills',
         description: 'Manage WorkOS skills for coding agents (Claude Code, Codex, Cursor, Goose)',
@@ -969,29 +979,61 @@ const commands = [
             { name: 'list', description: 'List vault objects', options: [...paginationOpts] },
             {
                 name: 'get',
-                description: 'Get a vault object',
+                description: 'Get a vault object (metadata only; use --decrypt to include value)',
                 positionals: [{ name: 'id', type: 'string', description: 'Object ID', required: true }],
+                options: [
+                    {
+                        name: 'decrypt',
+                        type: 'boolean',
+                        description: 'Include the decrypted secret value',
+                        required: false,
+                        default: false,
+                        hidden: false,
+                    },
+                ],
             },
             {
                 name: 'get-by-name',
-                description: 'Get a vault object by name',
+                description: 'Get a vault object by name (metadata only; use --decrypt to include value)',
                 positionals: [{ name: 'name', type: 'string', description: 'Object name', required: true }],
+                options: [
+                    {
+                        name: 'decrypt',
+                        type: 'boolean',
+                        description: 'Include the decrypted secret value',
+                        required: false,
+                        default: false,
+                        hidden: false,
+                    },
+                ],
             },
             {
                 name: 'create',
-                description: 'Create a vault object',
+                description: 'Create a vault object (reads value from stdin when --value is omitted or -)',
                 options: [
                     { name: 'name', type: 'string', description: 'Object name', required: true, hidden: false },
-                    { name: 'value', type: 'string', description: 'Secret value', required: true, hidden: false },
-                    { name: 'org', type: 'string', description: 'Organization ID', required: false, hidden: false },
+                    {
+                        name: 'value',
+                        type: 'string',
+                        description: 'Secret value (omit or use - to read from stdin)',
+                        required: false,
+                        hidden: false,
+                    },
+                    { name: 'org', type: 'string', description: 'Organization ID (required)', required: true, hidden: false },
                 ],
             },
             {
                 name: 'update',
-                description: 'Update a vault object',
+                description: 'Update a vault object (reads value from stdin when --value is omitted or -)',
                 positionals: [{ name: 'id', type: 'string', description: 'Object ID', required: true }],
                 options: [
-                    { name: 'value', type: 'string', description: 'New value', required: true, hidden: false },
+                    {
+                        name: 'value',
+                        type: 'string',
+                        description: 'New value (omit or use - to read from stdin)',
+                        required: false,
+                        hidden: false,
+                    },
                     { name: 'version-check', type: 'string', description: 'Version check ID', required: false, hidden: false },
                 ],
             },
@@ -1010,6 +1052,34 @@ const commands = [
                 description: 'List vault object versions',
                 positionals: [{ name: 'id', type: 'string', description: 'Object ID', required: true }],
             },
+            {
+                name: 'run',
+                description: 'Run a command with Vault secrets injected as environment variables',
+                options: [
+                    {
+                        name: 'secret',
+                        type: 'array',
+                        description: 'Map a vault object to an env var: ENV_VAR=vault-name (repeatable)',
+                        required: true,
+                        hidden: false,
+                    },
+                    {
+                        name: 'env',
+                        type: 'string',
+                        description: 'Environment name to read API key from (defaults to active)',
+                        required: false,
+                        hidden: false,
+                    },
+                    {
+                        name: 'dry-run',
+                        type: 'boolean',
+                        description: 'Print which secrets would be injected, no fetch',
+                        required: false,
+                        default: false,
+                        hidden: false,
+                    },
+                ],
+            },
         ],
     },
     {
@@ -1301,10 +1371,9 @@ const globalOptions = [
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
-const commandAliases = { org: 'organization' };
 const helpJsonCommandNames = new Set([
     ...commands.map((command) => command.name.split(' ')[0]),
-    ...Object.keys(commandAliases),
+    ...Object.keys(COMMAND_ALIASES),
 ]);
 /**
  * Extract the requested command from raw argv before yargs parses --help.
@@ -1323,7 +1392,7 @@ export function extractHelpJsonCommand(argv) {
             continue;
         }
         if (!arg.startsWith('-') && helpJsonCommandNames.has(arg)) {
-            return commandAliases[arg] ?? arg;
+            return COMMAND_ALIASES[arg] ?? arg;
         }
     }
     return undefined;
@@ -1334,6 +1403,14 @@ export function extractHelpJsonCommand(argv) {
  * @param subcommand - Optional command name to return a subtree for (e.g. "env").
  *                     Returns full tree if omitted or if command not found.
  */
+/**
+ * Top-level command names (first token of each registered command). Used by
+ * telemetry to recognise real commands without trusting arbitrary argv tokens
+ * (so option values / secrets are never recorded as a command name).
+ */
+export function getTopLevelCommandNames() {
+    return commands.map((c) => c.name.split(' ')[0]);
+}
 export function buildCommandTree(subcommand) {
     if (subcommand) {
         const match = commands.find((c) => c.name === subcommand);