feat(cli): warn on unrecognized CLI options

packages/aws-cdk/lib/cli/cli.ts

@@ -38,6 +38,7 @@ import { getLanguageFromAlias } from '../commands/language';
 import { getMigrateScanType } from '../commands/migrate';
 import { execProgram, CloudExecutable } from '../cxapp';
 import type { StackSelector, Synthesizer } from '../cxapp';
+import { findUnknownOptions } from './util/check-unknown-options';
 import { isCI } from './util/ci';
 import { guessAgent } from './util/guess-agent';
 
@@ -99,6 +100,12 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
   await ioHost.defaults.debug('CDK Toolkit CLI version:', versionWithBuild());
   await ioHost.defaults.debug('Command line arguments:', argv);
 
+  const unknownOptions = findUnknownOptions(argv);
+  if (unknownOptions.length > 0) {
+    const formatted = unknownOptions.map((o) => `--${o}`).join(', ');
+    await ioHost.defaults.warn(`Unknown option(s): ${formatted}. These will be ignored. Run 'cdk --help' to see available options.`);
+  }
+
   const configuration = await Configuration.fromArgsAndFiles(ioHelper,
     {
       commandLineArguments: {

packages/aws-cdk/lib/cli/util/check-unknown-options.ts

@@ -0,0 +1,92 @@
+/**
+ * Detect unrecognized CLI options and emit warnings.
+ *
+ * Yargs does not enable strict option checking by default, so unknown flags
+ * like `--region` (before it was added) are silently swallowed. This function
+ * compares the parsed argv keys against the known global and command options
+ * from the CLI type registry and warns for any that don't match.
+ */
+export function findUnknownOptions(argv: any): string[] {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const config = require('../cli-type-registry.json');
+  const command = argv._[0];
+
+  const globalOptions = new Set<string>(Object.keys(config.globalOptions));
+  const commandOptions = new Set<string>(Object.keys(config.commands[command]?.options ?? {}));
+
+  // Collect all known aliases and negativeAliases
+  for (const [, optDef] of Object.entries<any>(config.globalOptions)) {
+    if (optDef.alias) {
+      const aliases = Array.isArray(optDef.alias) ? optDef.alias : [optDef.alias];
+      for (const a of aliases) {
+        globalOptions.add(a);
+      }
+    }
+    if (optDef.negativeAlias) {
+      globalOptions.add(optDef.negativeAlias);
+    }
+  }
+  for (const [, optDef] of Object.entries<any>(config.commands[command]?.options ?? {})) {
+    if (optDef.alias) {
+      const aliases = Array.isArray(optDef.alias) ? optDef.alias : [optDef.alias];
+      for (const a of aliases) {
+        commandOptions.add(a);
+      }
+    }
+    if (optDef.negativeAlias) {
+      commandOptions.add(optDef.negativeAlias);
+    }
+  }
+
+  // yargs internal keys to ignore
+  const yargsInternals = new Set(['_', '$0', 'help', 'h', 'version']);
+
+  // The command's positional arg name
+  const commandArg = config.commands[command]?.arg?.name;
+  if (commandArg) {
+    yargsInternals.add(commandArg);
+  }
+
+  const unknown: string[] = [];
+  for (const key of Object.keys(argv)) {
+    if (argv[key] === undefined) continue;
+    if (yargsInternals.has(key)) continue;
+    if (globalOptions.has(key)) continue;
+    if (commandOptions.has(key)) continue;
+
+    // yargs creates camelCase versions of kebab-case options — skip those
+    const kebab = camelToKebab(key);
+    if (kebab !== key && (globalOptions.has(kebab) || commandOptions.has(kebab))) continue;
+
+    // yargs creates "noFoo" keys for --no-foo boolean negations — skip those
+    if (key.startsWith('no') && key.length > 2 && key[2] === key[2].toUpperCase()) {
+      const positiveKey = key[2].toLowerCase() + key.slice(3);
+      const positiveKebab = camelToKebab(positiveKey);
+      if (globalOptions.has(positiveKey) || commandOptions.has(positiveKey) ||
+          globalOptions.has(positiveKebab) || commandOptions.has(positiveKebab)) continue;
+    }
+
+    // yargs .env('CDK') injects CDK_* environment variables as camelCase argv
+    // keys (e.g. CDK_INTEG_ATMOSPHERE_POOL -> integAtmospherePool). These are
+    // intentional configuration from the environment, not user typos.
+    if (isFromEnvPrefix(key, 'CDK')) continue;
+
+    unknown.push(key);
+  }
+
+  return unknown;
+}
+
+function camelToKebab(str: string): string {
+  return str.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+
+/**
+ * Checks whether a camelCase argv key was injected by yargs' .env(PREFIX)
+ * feature. yargs converts PREFIX_FOO_BAR env vars into camelCase keys
+ * (fooBar). We reverse the mapping and check if the env var exists.
+ */
+function isFromEnvPrefix(key: string, prefix: string): boolean {
+  const screamingSnake = key.replace(/[A-Z]/g, (m) => `_${m}`).toUpperCase();
+  return process.env[`${prefix}_${screamingSnake}`] !== undefined;
+}

packages/aws-cdk/test/cli/util/check-unknown-options.test.ts

@@ -0,0 +1,120 @@
+import { findUnknownOptions } from '../../../lib/cli/util/check-unknown-options';
+
+describe('findUnknownOptions', () => {
+  test('returns empty array for known global options', () => {
+    const argv = {
+      _: ['deploy'],
+      $0: 'cdk',
+      profile: 'my-profile',
+      verbose: 1,
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('returns empty array for known command options', () => {
+    const argv = {
+      _: ['deploy'],
+      $0: 'cdk',
+      force: true,
+      all: false,
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('detects unknown options', () => {
+    const argv = {
+      _: ['bootstrap'],
+      $0: 'cdk',
+      profile: 'my-profile',
+      fakeOption: 'value',
+    };
+    const unknown = findUnknownOptions(argv);
+    expect(unknown).toContain('fakeOption');
+  });
+
+  test('does not report camelCase variants of known kebab-case options', () => {
+    const argv = {
+      '_': ['deploy'],
+      '$0': 'cdk',
+      'ca-bundle-path': '/tmp/ca.pem',
+      'caBundlePath': '/tmp/ca.pem',
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('does not report yargs internal keys', () => {
+    const argv = {
+      _: ['deploy'],
+      $0: 'cdk',
+      help: false,
+      h: false,
+      version: false,
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('does not report aliases', () => {
+    const argv = {
+      _: ['deploy'],
+      $0: 'cdk',
+      v: 1,
+      j: false,
+      a: 'node bin/app.js',
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('does not report yargs boolean negation keys (noFoo for --no-foo)', () => {
+    const argv = {
+      _: ['deploy'],
+      $0: 'cdk',
+      rollback: false,
+      noRollback: true,
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('does not report negativeAlias keys', () => {
+    const argv = {
+      _: ['deploy'],
+      $0: 'cdk',
+      R: true,
+      rollback: false,
+    };
+    expect(findUnknownOptions(argv)).toEqual([]);
+  });
+
+  test('does not report keys injected by yargs .env("CDK") from environment variables', () => {
+    process.env.CDK_INTEG_ATMOSPHERE_POOL = 'test-pool';
+    process.env.CDK_MAJOR_VERSION = '2';
+    try {
+      const argv = {
+        _: ['deploy'],
+        $0: 'cdk',
+        integAtmospherePool: 'test-pool',
+        majorVersion: '2',
+      };
+      expect(findUnknownOptions(argv)).toEqual([]);
+    } finally {
+      delete process.env.CDK_INTEG_ATMOSPHERE_POOL;
+      delete process.env.CDK_MAJOR_VERSION;
+    }
+  });
+
+  test('still reports truly unknown options even when CDK_ env vars exist', () => {
+    process.env.CDK_INTEG_ATMOSPHERE_POOL = 'test-pool';
+    try {
+      const argv = {
+        _: ['deploy'],
+        $0: 'cdk',
+        integAtmospherePool: 'test-pool',
+        totallyFakeOption: 'value',
+      };
+      const unknown = findUnknownOptions(argv);
+      expect(unknown).not.toContain('integAtmospherePool');
+      expect(unknown).toContain('totallyFakeOption');
+    } finally {
+      delete process.env.CDK_INTEG_ATMOSPHERE_POOL;
+    }
+  });
+});