feat: add config command with dot-notation support

integ-tests/config.test.ts

@@ -0,0 +1,101 @@
+import { spawnAndCollect } from '../src/test-utils/cli-runner.js';
+import { mkdtempSync, readFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+
+const testConfigDir = mkdtempSync(join(tmpdir(), 'agentcore-config-integ-'));
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.mjs');
+
+function run(args: string[]) {
+  return spawnAndCollect('node', [cliPath, ...args], tmpdir(), {
+    AGENTCORE_SKIP_INSTALL: '1',
+    AGENTCORE_CONFIG_DIR: testConfigDir,
+  });
+}
+
+function readConfig() {
+  return JSON.parse(readFileSync(join(testConfigDir, 'config.json'), 'utf-8'));
+}
+
+describe('config command', () => {
+  afterAll(() => rm(testConfigDir, { recursive: true, force: true }));
+
+  it('lists config with only installationId when fresh', async () => {
+    const result = await run(['config']);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed.installationId).toBeDefined();
+  });
+
+  it('sets a string value', async () => {
+    const result = await run(['config', 'uvIndex', 'https://example.com']);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain('Set uvIndex = https://example.com');
+    expect(readConfig().uvIndex).toBe('https://example.com');
+  });
+
+  it('gets a value', async () => {
+    const result = await run(['config', 'uvIndex']);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe('"https://example.com"');
+  });
+
+  it('sets a nested value with dot notation', async () => {
+    const result = await run(['config', 'telemetry.endpoint', 'https://metrics.example.com']);
+    expect(result.exitCode).toBe(0);
+    expect(readConfig().telemetry.endpoint).toBe('https://metrics.example.com');
+  });
+
+  it('gets a nested value with dot notation', async () => {
+    const result = await run(['config', 'telemetry.endpoint']);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe('"https://metrics.example.com"');
+  });
+
+  it('gets an object value as JSON', async () => {
+    const result = await run(['config', 'telemetry']);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed.endpoint).toBe('https://metrics.example.com');
+  });
+
+  it('sets a boolean value via JSON parsing', async () => {
+    const result = await run(['config', 'telemetry.enabled', 'true']);
+    expect(result.exitCode).toBe(0);
+    expect(readConfig().telemetry.enabled).toBe(true);
+  });
+
+  it('sets a numeric value via JSON parsing', async () => {
+    const result = await run(['config', 'transactionSearchIndexPercentage', '50']);
+    expect(result.exitCode).toBe(0);
+    expect(readConfig().transactionSearchIndexPercentage).toBe(50);
+  });
+
+  it('rejects invalid value for a typed key', async () => {
+    const result = await run(['config', 'telemetry.enabled', 'notabool']);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('Invalid value');
+  });
+
+  it('rejects unknown keys', async () => {
+    const result = await run(['config', 'foo.bar.baz', 'hello']);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('Invalid value');
+  });
+
+  it('returns error for unset key', async () => {
+    const result = await run(['config', 'disableTransactionSearch']);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('is not set');
+  });
+
+  it('lists all config after mutations', async () => {
+    const result = await run(['config']);
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed.uvIndex).toBe('https://example.com');
+    expect(parsed.telemetry.endpoint).toBe('https://metrics.example.com');
+  });
+});

src/cli/cli.ts

@@ -3,6 +3,7 @@ import { registerABTestCommand } from './commands/abtest';
 import { registerAdd } from './commands/add';
 import { registerAddTool } from './commands/add/tool-command';
 import { registerArchive } from './commands/archive';
+import { registerConfig } from './commands/config';
 import { registerConfigBundle } from './commands/config-bundle';
 import { registerCreate } from './commands/create';
 import { registerDataset } from './commands/dataset';
@@ -205,6 +206,7 @@ export function registerCommands(program: Command) {
   registerUpdate(program);
   registerValidate(program);
   registerConfigBundle(program);
+  registerConfig(program);
   registerDataset(program);
   registerArchive(program);
 

src/cli/commands/config/actions.ts

@@ -0,0 +1,69 @@
+import { readGlobalConfig, updateGlobalConfig, validateGlobalConfig } from '../../../lib/schemas/io/global-config.js';
+import type { ConfigResult } from './types.js';
+import { ValidationError } from '@/lib/index.js';
+
+export async function handleConfigList(): Promise<ConfigResult> {
+  const config = await readGlobalConfig();
+  return { success: true, message: JSON.stringify(config, null, 2) };
+}
+
+export async function handleConfigGet(key: string): Promise<ConfigResult> {
+  const config = await readGlobalConfig();
+  const value = getByPath(config, key);
+  if (value === undefined) {
+    return { success: false, error: new Error(`Key "${key}" is not set.`) };
+  }
+  const message = JSON.stringify(value, null, 2);
+  return { success: true, message };
+}
+
+export async function handleConfigSet(key: string, raw: string): Promise<ConfigResult> {
+  const value = parseValue(raw);
+  const partial = buildNestedObject(key, value);
+  const validation = validateGlobalConfig(partial);
+
+  if (!validation.success) {
+    return { success: false, error: new ValidationError(`Invalid value "${raw}" for key "${key}".`) };
+  }
+
+  const ok = await updateGlobalConfig(partial);
+  if (!ok) {
+    return { success: false, error: new Error(`Could not write config.`) };
+  }
+  return { success: true, message: `Set ${key} = ${raw}` };
+}
+
+function parseValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function isRecord(val: unknown): val is Record<string, unknown> {
+  return typeof val === 'object' && val !== null && !Array.isArray(val);
+}
+
+function getByPath(obj: Record<string, unknown>, path: string): unknown {
+  let current: unknown = obj;
+  for (const part of path.split('.')) {
+    if (!isRecord(current)) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function buildNestedObject(path: string, value: unknown): Record<string, unknown> {
+  const parts = path.split('.');
+  const leaf = parts.pop();
+  if (!leaf) return {};
+  const result: Record<string, unknown> = {};
+  const inner = parts.reduce<Record<string, unknown>>((acc, part) => {
+    const next: Record<string, unknown> = {};
+    acc[part] = next;
+    return next;
+  }, result);
+  inner[leaf] = value;
+  return result;
+}

src/cli/commands/config/command.ts

@@ -0,0 +1,31 @@
+import { COMMAND_DESCRIPTIONS } from '../../tui/copy.js';
+import { handleConfigGet, handleConfigList, handleConfigSet } from './actions.js';
+import type { ConfigResult } from './types.js';
+import type { Command } from '@commander-js/extra-typings';
+
+function resolveAction(key?: string, value?: string): () => Promise<ConfigResult> {
+  if (!key) return () => handleConfigList();
+  if (value === undefined) return () => handleConfigGet(key);
+  return () => handleConfigSet(key, value);
+}
+
+function printResult(result: ConfigResult): void {
+  if (result.success) {
+    console.log(result.message);
+  } else {
+    console.error(result.error.message);
+  }
+}
+
+export function registerConfig(program: Command) {
+  program
+    .command('config')
+    .description(COMMAND_DESCRIPTIONS.config)
+    .argument('[key]', 'Config key in dot notation (e.g. telemetry.enabled)')
+    .argument('[value]', 'Value to set')
+    .action(async (key?: string, value?: string) => {
+      const result = await resolveAction(key, value)();
+      printResult(result);
+      if (!result.success) process.exit(1);
+    });
+}

src/cli/commands/config/index.ts

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

src/cli/commands/config/types.ts

@@ -0,0 +1,3 @@
+import type { Result } from '../../../lib/result.js';
+
+export type ConfigResult = Result<{ message: string }>;

src/cli/telemetry/cli-command-run.ts

@@ -1,11 +1,12 @@
 import type { Result } from '../../lib/result';
+import { resilientParse } from '../../lib/utils/zod.js';
 import { getErrorMessage } from '../errors';
 import { type AttributeRecorder, createAttributeRecorder } from './attribute-recorder.js';
 import { TelemetryClientAccessor } from './client-accessor.js';
 import { TelemetryClient } from './client.js';
 import { classifyError } from './error.js';
 import { COMMAND_SCHEMAS, type Command, type CommandAttrs, deriveCommandGroup } from './schemas/command-run.js';
-import { type CommandResult, CommandResultSchema, resilientParse } from './schemas/common-shapes.js';
+import { type CommandResult, CommandResultSchema } from './schemas/common-shapes.js';
 import { performance } from 'perf_hooks';
 
 export type { AttributeRecorder } from './attribute-recorder.js';
@@ -30,7 +31,11 @@ function recordCommandRun<C extends Command>(
 
     const validatedAttrs =
       Object.keys(attrs as Record<string, unknown>).length > 0
-        ? resilientParse(COMMAND_SCHEMAS[command], attrs as Record<string, unknown>)
+        ? resilientParse(COMMAND_SCHEMAS[command], attrs as Record<string, unknown>, {
+            fallback: 'unknown',
+            fillMissing: true,
+            keepUnknown: false,
+          })
         : attrs;
 
     client.emit('cli.command_run', durationMs, {

src/cli/telemetry/schemas/__tests__/command-run.test.ts

@@ -1,6 +1,7 @@
+import { resilientParse } from '../../../../lib/utils/zod';
 import { COMMAND_SCHEMAS, type Command, type CommandAttrs, deriveCommandGroup } from '../command-run';
 import { ResourceAttributesSchema } from '../common-attributes';
-import { CommandResultSchema, resilientParse } from '../common-shapes';
+import { CommandResultSchema } from '../common-shapes';
 import { describe, expect, expectTypeOf, it } from 'vitest';
 import { z } from 'zod';
 
@@ -237,6 +238,8 @@ describe('type safety', () => {
   });
 });
 
+const TELEMETRY_OPTS = { fallback: 'unknown', fillMissing: true, keepUnknown: false } as const;
+
 describe('resilientParse', () => {
   it('passes valid attrs through unchanged', () => {
     const attrs = {
@@ -250,7 +253,7 @@ describe('resilientParse', () => {
       network_mode: 'public',
       has_agent: true,
     };
-    expect(resilientParse(COMMAND_SCHEMAS.create, attrs)).toEqual(attrs);
+    expect(resilientParse(COMMAND_SCHEMAS.create, attrs, TELEMETRY_OPTS)).toEqual(attrs);
   });
 
   it('defaults a single invalid enum field to unknown', () => {
@@ -265,26 +268,26 @@ describe('resilientParse', () => {
       network_mode: 'public',
       has_agent: true,
     };
-    const result = resilientParse(COMMAND_SCHEMAS.create, attrs);
+    const result = resilientParse(COMMAND_SCHEMAS.create, attrs, TELEMETRY_OPTS);
     expect(result.agent_language).toBe('unknown');
     expect(result.agent_framework).toBe('strands');
   });
 
   it('defaults missing required fields to unknown', () => {
-    const result = resilientParse(COMMAND_SCHEMAS.create, { agent_language: 'python' });
+    const result = resilientParse(COMMAND_SCHEMAS.create, { agent_language: 'python' }, TELEMETRY_OPTS);
     expect(result.agent_language).toBe('python');
     expect(result.agent_framework).toBe('unknown');
     expect(result.model_provider).toBe('unknown');
   });
 
   it('defaults all fields to unknown when all are invalid', () => {
-    const result = resilientParse(COMMAND_SCHEMAS.create, {});
+    const result = resilientParse(COMMAND_SCHEMAS.create, {}, TELEMETRY_OPTS);
     for (const value of Object.values(result)) {
       expect(value).toBe('unknown');
     }
   });
 
   it('returns empty object for no-attrs schemas', () => {
-    expect(resilientParse(COMMAND_SCHEMAS['telemetry.disable'], {})).toEqual({});
+    expect(resilientParse(COMMAND_SCHEMAS['telemetry.disable'], {}, TELEMETRY_OPTS)).toEqual({});
   });
 });

src/cli/telemetry/schemas/common-shapes.ts

@@ -8,24 +8,6 @@ export function safeSchema<T extends Record<string, SafeField>>(shape: T) {
   return z.object(shape);
 }
 
-/**
- * Validate each field in a schema individually, defaulting to 'unknown' on failure.
- * This ensures a single invalid attribute never blocks the entire metric from being published.
- * Keys in attrs not present in the schema are omitted from the result.
- */
-export function resilientParse(
-  schema: z.ZodObject<z.ZodRawShape>,
-  attrs: Record<string, unknown>
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  for (const key of Object.keys(schema.shape)) {
-    const field = schema.shape[key] as z.ZodType;
-    const parsed = field.safeParse(attrs[key]);
-    result[key] = parsed.success ? parsed.data : 'unknown';
-  }
-  return result;
-}
-
 /**
  * Lowercase a CLI value and parse it through a Zod enum, returning the narrowed type.
  * The `as` cast on the failure branch is intentional: invalid values pass through to

src/cli/tui/copy.ts

@@ -56,6 +56,7 @@ export const COMMAND_DESCRIPTIONS = {
   validate: 'Validate agentcore/ config files.',
   'config-bundle': '[preview] Manage configuration bundle versions and diffs.',
   archive: '[preview] Archive (delete) a batch evaluation or recommendation on the service and clear local history.',
+  config: 'Adjust global configuration settings such as telemetry opt-out status',
 } as const;
 
 /**