feat(cli): add git repository support for custom init templates

packages/@aws-cdk/user-input-gen/lib/yargs-gen.ts

@@ -105,17 +105,22 @@ function makeYargs(config: CliConfig, helpers: CliHelpers): Statement {
     }
     commandCallArgs.push(lit(commandFacts.description));
 
-    if (commandFacts.options) {
-      commandCallArgs.push(optionsExpr);
-    }
-
     // Add implies calls if present
     if (commandFacts.implies) {
       for (const [key, value] of Object.entries(commandFacts.implies)) {
         optionsExpr = optionsExpr.callMethod('implies', lit(key), lit(value));
       }
     }
 
+    // Add check function if present
+    if (commandFacts.check) {
+      optionsExpr = optionsExpr.callMethod('check', code.expr.directCode(commandFacts.check.toString()));
+    }
+
+    if (commandFacts.options || commandFacts.check) {
+      commandCallArgs.push(optionsExpr);
+    }
+
     yargsExpr = yargsExpr.callMethod('command', ...commandCallArgs);
   }
 

packages/@aws-cdk/user-input-gen/lib/yargs-types.ts

@@ -8,6 +8,7 @@ interface YargsCommand {
 export interface CliAction extends YargsCommand {
   options?: { [optionName: string]: CliOption };
   implies?: { [key: string]: string };
+  check?: (argv: any) => boolean | Promise<boolean>;
 }
 
 interface YargsArg {

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

@@ -401,10 +401,18 @@ export async function makeConfig(): Promise<CliConfig> {
           'list': { type: 'boolean', desc: 'List the available templates' },
           'generate-only': { type: 'boolean', default: false, desc: 'If true, only generates project files, without executing additional operations such as setting up a git repo, installing dependencies or compiling the project' },
           'lib-version': { type: 'string', alias: 'V', default: undefined, desc: 'The version of the CDK library (aws-cdk-lib) to initialize built-in templates with. Defaults to the version that was current when this CLI was built.' },
-          'from-path': { type: 'string', desc: 'Path to a local custom template directory or multi-template repository', requiresArg: true, conflicts: ['lib-version'] },
+          'from-path': { type: 'string', desc: 'Path to a local custom template directory or multi-template repository', requiresArg: true, conflicts: ['lib-version', 'from-git-url'] },
+          'from-git-url': { type: 'string', desc: 'Git repository URL to clone custom template from', requiresArg: true, conflicts: ['lib-version', 'from-path'] },
           'template-path': { type: 'string', desc: 'Path to a specific template within a multi-template repository', requiresArg: true },
         },
-        implies: { 'template-path': 'from-path' },
+        check: (argv: any) => {
+          if (argv['template-path'] && !argv['from-path'] && !argv['from-git-url']) {
+            const error = new Error('--template-path can only be used with --from-path or --from-git-url');
+            error.name = 'ValidationError';
+            throw error;
+          }
+          return true;
+        },
       },
       'migrate': {
         description: 'Migrate existing AWS resources into a CDK app',

packages/aws-cdk/lib/cli/cli-type-registry.json

@@ -872,17 +872,24 @@
           "desc": "Path to a local custom template directory or multi-template repository",
           "requiresArg": true,
           "conflicts": [
-            "lib-version"
+            "lib-version",
+            "from-git-url"
+          ]
+        },
+        "from-git-url": {
+          "type": "string",
+          "desc": "Git repository URL to clone custom template from",
+          "requiresArg": true,
+          "conflicts": [
+            "lib-version",
+            "from-path"
           ]
         },
         "template-path": {
           "type": "string",
           "desc": "Path to a specific template within a multi-template repository",
           "requiresArg": true
         }
-      },
-      "implies": {
-        "template-path": "from-path"
       }
     },
     "migrate": {

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

@@ -517,7 +517,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
           return printAvailableTemplates(ioHelper, language);
         } else {
           // Gate custom template support with unstable flag
-          if (args['from-path'] && !configuration.settings.get(['unstable']).includes('init')) {
+          if ((args['from-path'] || args['from-git-url']) && !configuration.settings.get(['unstable']).includes('init')) {
             throw new ToolkitError('Unstable feature use: \'init\' with custom templates is unstable. It must be opted in via \'--unstable\', e.g. \'cdk init --from-path=./my-template --unstable=init\'');
           }
           return cliInit({
@@ -528,6 +528,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
             generateOnly: args.generateOnly,
             libVersion: args.libVersion,
             fromPath: args['from-path'],
+            fromGitUrl: args['from-git-url'],
             templatePath: args['template-path'],
           });
         }

packages/aws-cdk/lib/cli/convert-to-user-input.ts

@@ -246,6 +246,7 @@ export function convertYargsToUserInput(args: any): UserInput {
         generateOnly: args.generateOnly,
         libVersion: args.libVersion,
         fromPath: args.fromPath,
+        fromGitUrl: args.fromGitUrl,
         templatePath: args.templatePath,
         TEMPLATE: args.TEMPLATE,
       };
@@ -484,6 +485,7 @@ export function convertConfigToUserInput(config: any): UserInput {
     generateOnly: config.init?.generateOnly,
     libVersion: config.init?.libVersion,
     fromPath: config.init?.fromPath,
+    fromGitUrl: config.init?.fromGitUrl,
     templatePath: config.init?.templatePath,
   };
   const migrateOptions = {

packages/aws-cdk/lib/cli/parse-command-line-arguments.ts

@@ -869,13 +869,28 @@ export function parseCommandLineArguments(args: Array<string>): any {
           type: 'string',
           desc: 'Path to a local custom template directory or multi-template repository',
           requiresArg: true,
-          conflicts: ['lib-version'],
+          conflicts: ['lib-version', 'from-git-url'],
+        })
+        .option('from-git-url', {
+          default: undefined,
+          type: 'string',
+          desc: 'Git repository URL to clone custom template from',
+          requiresArg: true,
+          conflicts: ['lib-version', 'from-path'],
         })
         .option('template-path', {
           default: undefined,
           type: 'string',
           desc: 'Path to a specific template within a multi-template repository',
           requiresArg: true,
+        })
+        .check((argv) => {
+          if (argv['template-path'] && !argv['from-path'] && !argv['from-git-url']) {
+            const error = new Error('--template-path can only be used with --from-path or --from-git-url');
+            error.name = 'ValidationError';
+            throw error;
+          }
+          return true;
         }),
     )
     .command('migrate', 'Migrate existing AWS resources into a CDK app', (yargs: Argv) =>

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

@@ -1378,6 +1378,13 @@ export interface InitOptions {
    */
   readonly fromPath?: string;
 
+  /**
+   * Git repository URL to clone custom template from
+   *
+   * @default - undefined
+   */
+  readonly fromGitUrl?: string;
+
   /**
    * Path to a specific template within a multi-template repository
    *

packages/aws-cdk/lib/commands/init/init.ts

@@ -1,4 +1,5 @@
 import * as childProcess from 'child_process';
+import * as os from 'os';
 import * as path from 'path';
 import { ToolkitError } from '@aws-cdk/toolkit-lib';
 import * as chalk from 'chalk';
@@ -66,10 +67,16 @@ export interface CliInitOptions {
   readonly fromPath?: string;
 
   /**
-   * Path to a specific template within a multi-template repository.
-   * This parameter requires --from-path to be specified.
+   * Git repository URL to clone and use as template source
    * @default undefined
    */
+  readonly fromGitUrl?: string;
+
+  /**
+   * Path to a specific template within a multi-template repository.
+   * This parameter requires --from-path or --from-git-url to be specified.
+   * @default undefined - Optional/auto-detected if repository contains only one template, otherwise required
+   */
   readonly templatePath?: string;
 
   readonly ioHelper: IoHelper;
@@ -85,15 +92,21 @@ export async function cliInit(options: CliInitOptions) {
   const workDir = options.workDir ?? process.cwd();
 
   // Show available templates if no type and no language provided (main branch logic)
-  if (!options.fromPath && !options.type && !options.language) {
+  if (!options.fromPath && !options.fromGitUrl && !options.type && !options.language) {
     await printAvailableTemplates(ioHelper);
     return;
   }
 
   // Step 1: Load template
   let template: InitTemplate;
+  let gitTempDir: string | undefined;
+
   if (options.fromPath) {
     template = await loadLocalTemplate(options.fromPath, options.templatePath);
+  } else if (options.fromGitUrl) {
+    const result = await loadGitTemplate(options.fromGitUrl, options.templatePath);
+    template = result.template;
+    gitTempDir = result.tempDir;
   } else {
     template = await loadBuiltinTemplate(ioHelper, options.type, options.language);
   }
@@ -102,17 +115,25 @@ export async function cliInit(options: CliInitOptions) {
   const language = await resolveLanguage(ioHelper, template, options.language, options.type);
 
   // Step 3: Initialize project following standard process
-  await initializeProject(
-    ioHelper,
-    template,
-    language,
-    canUseNetwork,
-    generateOnly,
-    workDir,
-    options.stackName,
-    options.migrate,
-    options.libVersion,
-  );
+  try {
+    await initializeProject(
+      ioHelper,
+      template,
+      language,
+      canUseNetwork,
+      generateOnly,
+      workDir,
+      options.stackName,
+      options.migrate,
+      options.libVersion,
+    );
+  } finally {
+    // Clean up git temp directory if it exists
+    if (gitTempDir) {
+      await fs.remove(gitTempDir).catch(() => {
+      });
+    }
+  }
 }
 
 /**
@@ -156,6 +177,34 @@ async function loadLocalTemplate(fromPath: string, templatePath?: string): Promi
   }
 }
 
+/**
+ * Load a template from a Git repository URL
+ * @param gitUrl - Git repository URL to clone
+ * @param templatePath - Optional path to a specific template within the repository
+ * @returns Promise resolving to the loaded InitTemplate and tempDir for cleanup
+ */
+async function loadGitTemplate(gitUrl: string, templatePath?: string): Promise<{ template: InitTemplate; tempDir: string }> {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cdk-init-git-'));
+
+  try {
+    // Clone repository (defaults to main/master branch)
+    await executeGitCommand('git', ['clone', '--depth', '1', gitUrl, tempDir]);
+
+    // Now that we have the repository locally, use the same logic as loadLocalTemplate
+    const template = await loadLocalTemplate(tempDir, templatePath);
+
+    return { template, tempDir };
+  } catch (error: any) {
+    await fs.remove(tempDir).catch(() => {
+    });
+    if (error.message?.includes('not found') || error.code === 'ENOENT') {
+      throw new ToolkitError('Git is not installed or not available in PATH. Please install Git to use --from-git-url.');
+    }
+    const displayPath = templatePath ? `${gitUrl}/${templatePath}` : gitUrl;
+    throw new ToolkitError(`Failed to load template from Git repository: ${displayPath}. ${error.message}`);
+  }
+}
+
 /**
  * Load a built-in template by name
  */
@@ -843,6 +892,36 @@ function isRoot(dir: string) {
   return path.dirname(dir) === dir;
 }
 
+/**
+ * Execute a Git command with error handling
+ * @param cmd - Command to execute
+ * @param args - Command arguments
+ * @returns Promise resolving to stdout
+ */
+async function executeGitCommand(cmd: string, args: string[]): Promise<string> {
+  const child = childProcess.spawn(cmd, args, {
+    shell: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  let stdout = '';
+  let stderr = '';
+
+  child.stdout.on('data', (chunk) => (stdout += chunk.toString()));
+  child.stderr.on('data', (chunk) => (stderr += chunk.toString()));
+
+  return new Promise<string>((resolve, reject) => {
+    child.once('error', (err) => reject(err));
+    child.once('exit', (status) => {
+      if (status === 0) {
+        resolve(stdout);
+      } else {
+        reject(new ToolkitError(`Git command failed: ${stderr || stdout}`));
+      }
+    });
+  });
+}
+
 /**
  * Executes `command`. STDERR is emitted in real-time.
  *

packages/aws-cdk/test/commands/init.test.ts

@@ -606,30 +606,25 @@ describe('constructs version', () => {
     })).rejects.toThrow();
   });
 
-  cliTest('template-path implies from-path validation works', async (workDir) => {
-    // Test that the implication is properly configured
-    const { makeConfig } = await import('../../lib/cli/cli-config');
-    const config = await makeConfig();
-    expect(config.commands.init.implies).toEqual({ 'template-path': 'from-path' });
-
-    // Test that template-path functionality works when from-path is provided
-    const repoDir = await createMultiTemplateRepository(workDir, [
-      { name: 'implies-test', languages: ['typescript'] },
-    ]);
-    const projectDir = path.join(workDir, 'my-project');
-    await fs.mkdirp(projectDir);
+  cliTest('template-path validation requires from-path or from-git-url', async (workDir) => {
+    const { exec } = await import('child_process');
+    const { promisify } = await import('util');
+    const execAsync = promisify(exec);
+    const cdkBin = path.join(__dirname, '..', '..', 'bin', 'cdk');
 
-    await cliInit({
-      ioHelper,
-      fromPath: repoDir,
-      templatePath: 'implies-test',
-      language: 'typescript',
-      canUseNetwork: false,
-      generateOnly: true,
-      workDir: projectDir,
-    });
+    const emptyDir = path.join(workDir, 'empty-project');
+    await fs.mkdirp(emptyDir);
 
-    expect(await fs.pathExists(path.join(projectDir, 'app.ts'))).toBeTruthy();
+    // Test that template-path fails when used without from-path or from-git-url
+    try {
+      await execAsync(`node ${cdkBin} init --template-path some-template --language typescript --generate-only`, {
+        cwd: emptyDir,
+        env: { ...process.env, CDK_DISABLE_VERSION_CHECK: '1' },
+      });
+      throw new Error('Expected command to fail but it succeeded');
+    } catch (error: any) {
+      expect(error.stderr || error.message).toContain('--template-path can only be used with --from-path or --from-git-url');
+    }
   });
 
   cliTest('hook files are ignored during template copy', async (workDir) => {