feat: add telemetry preference controls and preinstall notice

Add user-facing telemetry controls (opt-out command, env var support,
config file, preinstall notice) without collecting any data. This
establishes the user-facing messaging before launch.

- Add `agentcore telemetry` command with enable/disable/status subcommands
- Add telemetry notice as a warning in preinstall script (shown on install/upgrade)
- Support AGENTCORE_TELEMETRY_DISABLED and DO_NOT_TRACK env vars
- Add global config module (~/.agentcore/config.json) for persisting preferences
- Refactor update-notifier to reuse shared GLOBAL_CONFIG_DIR constant
- Add unit tests for global config, preference resolution, and command actions

Author: jesseturner21

package.json

@@ -43,7 +43,7 @@
     "scripts"
   ],
   "scripts": {
-    "preinstall": "node scripts/check-old-cli.mjs",
+    "preinstall": "node scripts/preinstall-warnings.mjs",
     "build": "npm run build:lib && npm run build:cli && npm run build:assets",
     "build:lib": "tsc -p tsconfig.build.json",
     "build:cli": "node esbuild.config.mjs",

scripts/check-old-cli.mjs scripts/preinstall-warnings.mjsscripts/check-old-cli.mjs renamed to scripts/preinstall-warnings.mjs

@@ -24,3 +24,19 @@ try {
 } catch {
   // No agentcore binary found or unexpected error — nothing to do
 }
+
+// Telemetry notice — shown on every install/upgrade
+try {
+  console.warn(
+    [
+      '',
+      '\x1b[33m⚠ NOTICE: The AgentCore CLI collects aggregated, anonymous usage\x1b[0m',
+      '\x1b[33manalytics to help improve the tool. To opt out, run:\x1b[0m',
+      '\x1b[33m  agentcore telemetry disable\x1b[0m',
+      '\x1b[33mOr set: AGENTCORE_TELEMETRY_DISABLED=true\x1b[0m',
+      '',
+    ].join('\n')
+  );
+} catch {
+  // Never fail the install
+}

src/cli/__tests__/global-config.test.ts

@@ -0,0 +1,87 @@
+import { GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_FILE, readGlobalConfig, updateGlobalConfig } from '../global-config';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('fs/promises');
+
+const mockMkdir = vi.mocked(mkdir);
+const mockReadFile = vi.mocked(readFile);
+const mockWriteFile = vi.mocked(writeFile);
+
+describe('global-config', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('readGlobalConfig', () => {
+    it('returns parsed config when file exists', async () => {
+      mockReadFile.mockResolvedValue(JSON.stringify({ telemetry: { enabled: false } }));
+
+      const config = await readGlobalConfig();
+
+      expect(config).toEqual({ telemetry: { enabled: false } });
+      expect(mockReadFile).toHaveBeenCalledWith(GLOBAL_CONFIG_FILE, 'utf-8');
+    });
+
+    it('returns empty object when file does not exist', async () => {
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+
+      const config = await readGlobalConfig();
+
+      expect(config).toEqual({});
+    });
+
+    it('returns empty object when file contains invalid JSON', async () => {
+      mockReadFile.mockResolvedValue('not json');
+
+      const config = await readGlobalConfig();
+
+      expect(config).toEqual({});
+    });
+  });
+
+  describe('updateGlobalConfig', () => {
+    it('creates directory and writes merged config', async () => {
+      mockReadFile.mockResolvedValue(JSON.stringify({ telemetry: { enabled: true } }));
+      mockMkdir.mockResolvedValue(undefined);
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await updateGlobalConfig({ telemetry: { enabled: false } });
+
+      expect(mockMkdir).toHaveBeenCalledWith(GLOBAL_CONFIG_DIR, { recursive: true });
+      const written = JSON.parse(mockWriteFile.mock.calls[0]![1] as string);
+      expect(written).toEqual({ telemetry: { enabled: false } });
+    });
+
+    it('merges telemetry sub-object without overwriting other keys', async () => {
+      mockReadFile.mockResolvedValue(JSON.stringify({ telemetry: { enabled: true } }));
+      mockMkdir.mockResolvedValue(undefined);
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await updateGlobalConfig({ telemetry: { enabled: false } });
+
+      const written = JSON.parse(mockWriteFile.mock.calls[0]![1] as string);
+      expect(written).toEqual({ telemetry: { enabled: false } });
+    });
+
+    it('silently ignores write failures', async () => {
+      mockReadFile.mockResolvedValue('{}');
+      mockMkdir.mockResolvedValue(undefined);
+      mockWriteFile.mockRejectedValue(new Error('EACCES'));
+
+      // Should not throw
+      await updateGlobalConfig({ telemetry: { enabled: true } });
+    });
+
+    it('handles missing existing config gracefully', async () => {
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+      mockMkdir.mockResolvedValue(undefined);
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await updateGlobalConfig({ telemetry: { enabled: true } });
+
+      const written = JSON.parse(mockWriteFile.mock.calls[0]![1] as string);
+      expect(written).toEqual({ telemetry: { enabled: true } });
+    });
+  });
+});

src/cli/cli.ts

@@ -7,6 +7,7 @@ import { registerInvoke } from './commands/invoke';
 import { registerPackage } from './commands/package';
 import { registerRemove } from './commands/remove';
 import { registerStatus } from './commands/status';
+import { registerTelemetry } from './commands/telemetry';
 import { registerUpdate } from './commands/update';
 import { registerValidate } from './commands/validate';
 import { PACKAGE_VERSION } from './constants';
@@ -132,6 +133,7 @@ export function registerCommands(program: Command) {
   registerPackage(program);
   registerRemove(program);
   registerStatus(program);
+  registerTelemetry(program);
   registerUpdate(program);
   registerValidate(program);
 }

src/cli/commands/telemetry/__tests__/telemetry.test.ts

@@ -0,0 +1,92 @@
+import * as globalConfig from '../../../global-config';
+import * as resolve from '../../../telemetry/resolve';
+import { handleTelemetryDisable, handleTelemetryEnable, handleTelemetryStatus } from '../actions';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../../../global-config');
+vi.mock('../../../telemetry/resolve');
+
+const mockUpdateGlobalConfig = vi.mocked(globalConfig.updateGlobalConfig);
+const mockResolveTelemetryPreference = vi.mocked(resolve.resolveTelemetryPreference);
+
+describe('telemetry actions', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    mockUpdateGlobalConfig.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  describe('handleTelemetryDisable', () => {
+    it('writes disabled config and prints confirmation', async () => {
+      await handleTelemetryDisable();
+
+      expect(mockUpdateGlobalConfig).toHaveBeenCalledWith({ telemetry: { enabled: false } });
+      expect(consoleSpy).toHaveBeenCalledWith('Telemetry has been disabled.');
+    });
+  });
+
+  describe('handleTelemetryEnable', () => {
+    it('writes enabled config and prints confirmation', async () => {
+      await handleTelemetryEnable();
+
+      expect(mockUpdateGlobalConfig).toHaveBeenCalledWith({ telemetry: { enabled: true } });
+      expect(consoleSpy).toHaveBeenCalledWith('Telemetry has been enabled.');
+    });
+  });
+
+  describe('handleTelemetryStatus', () => {
+    it('shows enabled status with default source', async () => {
+      mockResolveTelemetryPreference.mockResolvedValue({ enabled: true, source: 'default' });
+
+      await handleTelemetryStatus();
+
+      expect(consoleSpy).toHaveBeenCalledWith('Telemetry: Enabled');
+      expect(consoleSpy).toHaveBeenCalledWith('Source: default');
+    });
+
+    it('shows disabled status with global-config source', async () => {
+      mockResolveTelemetryPreference.mockResolvedValue({ enabled: false, source: 'global-config' });
+
+      await handleTelemetryStatus();
+
+      expect(consoleSpy).toHaveBeenCalledWith('Telemetry: Disabled');
+      expect(consoleSpy).toHaveBeenCalledWith('Source: global config (~/.agentcore/config.json)');
+    });
+
+    it('shows env var note when source is environment (AGENTCORE_TELEMETRY_DISABLED)', async () => {
+      const originalEnv = process.env;
+      process.env = { ...originalEnv, AGENTCORE_TELEMETRY_DISABLED: 'true' };
+
+      mockResolveTelemetryPreference.mockResolvedValue({ enabled: false, source: 'environment' });
+
+      await handleTelemetryStatus();
+
+      expect(consoleSpy).toHaveBeenCalledWith('Telemetry: Disabled');
+      expect(consoleSpy).toHaveBeenCalledWith('Source: environment variable');
+      expect(consoleSpy).toHaveBeenCalledWith('\nNote: AGENTCORE_TELEMETRY_DISABLED=true is set in your environment.');
+
+      process.env = originalEnv;
+    });
+
+    it('shows env var note when source is environment (DO_NOT_TRACK)', async () => {
+      const originalEnv = process.env;
+      process.env = { ...originalEnv, DO_NOT_TRACK: '1' };
+      delete process.env.AGENTCORE_TELEMETRY_DISABLED;
+
+      mockResolveTelemetryPreference.mockResolvedValue({ enabled: false, source: 'environment' });
+
+      await handleTelemetryStatus();
+
+      expect(consoleSpy).toHaveBeenCalledWith('\nNote: DO_NOT_TRACK=1 is set in your environment.');
+
+      process.env = originalEnv;
+    });
+  });
+});

src/cli/commands/telemetry/actions.ts

@@ -0,0 +1,40 @@
+import { updateGlobalConfig } from '../../global-config.js';
+import { resolveTelemetryPreference } from '../../telemetry/resolve.js';
+
+export async function handleTelemetryDisable(): Promise<void> {
+  await updateGlobalConfig({ telemetry: { enabled: false } });
+  console.log('Telemetry has been disabled.');
+}
+
+export async function handleTelemetryEnable(): Promise<void> {
+  await updateGlobalConfig({ telemetry: { enabled: true } });
+  console.log('Telemetry has been enabled.');
+}
+
+export async function handleTelemetryStatus(): Promise<void> {
+  const pref = await resolveTelemetryPreference();
+
+  const status = pref.enabled ? 'Enabled' : 'Disabled';
+
+  const sourceLabel =
+    pref.source === 'environment'
+      ? 'environment variable'
+      : pref.source === 'global-config'
+        ? 'global config (~/.agentcore/config.json)'
+        : 'default';
+
+  console.log(`Telemetry: ${status}`);
+  console.log(`Source: ${sourceLabel}`);
+
+  if (pref.source === 'environment') {
+    // eslint-disable-next-line @typescript-eslint/dot-notation
+    const agentcoreEnv = process.env['AGENTCORE_TELEMETRY_DISABLED'];
+    // eslint-disable-next-line @typescript-eslint/dot-notation
+    const doNotTrack = process.env['DO_NOT_TRACK'];
+    if (agentcoreEnv !== undefined) {
+      console.log(`\nNote: AGENTCORE_TELEMETRY_DISABLED=${agentcoreEnv} is set in your environment.`);
+    } else if (doNotTrack !== undefined) {
+      console.log(`\nNote: DO_NOT_TRACK=${doNotTrack} is set in your environment.`);
+    }
+  }
+}

src/cli/commands/telemetry/command.ts

@@ -0,0 +1,34 @@
+import { COMMAND_DESCRIPTIONS } from '../../tui/copy.js';
+import { handleTelemetryDisable, handleTelemetryEnable, handleTelemetryStatus } from './actions.js';
+import type { Command } from '@commander-js/extra-typings';
+
+export function registerTelemetry(program: Command) {
+  const telemetry = program
+    .command('telemetry')
+    .description(COMMAND_DESCRIPTIONS.telemetry)
+    .argument('[subcommand]', 'Subcommand to run (enable, disable, status)')
+    .action(() => {
+      telemetry.outputHelp();
+    });
+
+  telemetry
+    .command('disable')
+    .description('Disable anonymous usage analytics')
+    .action(async () => {
+      await handleTelemetryDisable();
+    });
+
+  telemetry
+    .command('enable')
+    .description('Enable anonymous usage analytics')
+    .action(async () => {
+      await handleTelemetryEnable();
+    });
+
+  telemetry
+    .command('status')
+    .description('Show current telemetry preference and source')
+    .action(async () => {
+      await handleTelemetryStatus();
+    });
+}

src/cli/commands/telemetry/index.ts

@@ -0,0 +1 @@
+export { registerTelemetry } from './command.js';

src/cli/global-config.ts

@@ -0,0 +1,39 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const GLOBAL_CONFIG_DIR = join(homedir(), '.agentcore');
+export const GLOBAL_CONFIG_FILE = join(GLOBAL_CONFIG_DIR, 'config.json');
+
+export interface GlobalConfig {
+  telemetry?: {
+    enabled?: boolean;
+  };
+}
+
+export async function readGlobalConfig(): Promise<GlobalConfig> {
+  try {
+    const data = await readFile(GLOBAL_CONFIG_FILE, 'utf-8');
+    return JSON.parse(data) as GlobalConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function updateGlobalConfig(partial: GlobalConfig): Promise<void> {
+  try {
+    const existing = await readGlobalConfig();
+
+    // Shallow merge with one level of nesting for telemetry sub-object
+    const merged: GlobalConfig = { ...existing };
+
+    if (partial.telemetry !== undefined) {
+      merged.telemetry = { ...existing.telemetry, ...partial.telemetry };
+    }
+
+    await mkdir(GLOBAL_CONFIG_DIR, { recursive: true });
+    await writeFile(GLOBAL_CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf-8');
+  } catch {
+    // Silently ignore write failures
+  }
+}