feat: add new netlify clone command, to clone an existing repo + connected Netlify site in one step (#7260)

* refactor(link): extract function for site by repo URL

This also polishes the progress output and fixes some types.

* feat: add `clone` command

When a user already has an existing Netlify site connected to a hosted git repo, pulling
this down and preparing it for use with Netlify CLI currently requires numerous steps:
1. find and copy the git remote URL
2. run `git clone <git url>`
3. run `cd <created dir>`
4. run `netlify link`
5. follow prompt to select "Use current git remote origin"

This is a very common flow, e.g. when using a "Deploy to Netlify" button, creating a site
from a Netlify template, creating a site from an AI creator... any workflow where the site
is created outside Netlify CLI requires several steps to get it ready for use with Netlify CLI.

This introduces a new command which vastly simplifies these steps:
1. find and copy the git remote URL
2. run `netlify clone <git url>`

This will clone the git repo, find the corresponding Netlify site, and link the created
directory automatically. It will only prompt the user if necessary - for example if the
git repo URL matches multiple sites.

For convenience and future integration into the Netlify platform and docs, I also included
support for explicitly passing the known site id or name via `--id` or `--name`.

Author: serhalp

docs/commands/clone.md

@@ -0,0 +1,49 @@
+---
+title: Netlify CLI clone command
+sidebar:
+  label: clone
+description: Clone a remote repo and link it to an existing site on Netlify
+---
+
+# `clone`
+
+<!-- AUTO-GENERATED-CONTENT:START (GENERATE_COMMANDS_DOCS) -->
+Clone a remote repository and link it to an existing site on Netlify
+Use this command when the existing Netlify site is already configured to deploy from the existing repo.
+
+If you specify a target directory, the repo will be cloned into that directory. By default, a directory will be created with the name of the repo.
+
+To specify a site, use --id or --name. By default, the Netlify site to link will be automatically detected if exactly one site found is found with a matching git URL. If we cannot find such a site, you will be interactively prompted to select one.
+
+**Usage**
+
+```bash
+netlify clone
+```
+
+**Arguments**
+
+- repo - URL of the repository to clone or Github `owner/repo` (required)
+- targetDir - directory in which to clone the repository - will be created if it does not exist
+
+**Flags**
+
+- `filter` (*string*) - For monorepos, specify the name of the application to run the command in
+- `id` (*string*) - ID of existing Netlify site to link to
+- `name` (*string*) - Name of existing Netlify site to link to
+- `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
+
+**Examples**
+
+```bash
+netlify clone vibecoder/next-unicorn
+netlify clone https://github.com/vibecoder/next-unicorn.git
+netlify clone git@github.com:vibecoder/next-unicorn.git
+netlify clone vibecoder/next-unicorn ./next-unicorn-shh-secret
+netlify clone --id 123-123-123-123 vibecoder/next-unicorn
+netlify clone --name my-site-name vibecoder/next-unicorn
+```
+
+
+<!-- AUTO-GENERATED-CONTENT:END -->

docs/commands/link.md

@@ -20,6 +20,7 @@ netlify link
 
 - `filter` (*string*) - For monorepos, specify the name of the application to run the command in
 - `git-remote-name` (*string*) - Name of Git remote to use. e.g. "origin"
+- `git-remote-url` (*string*) - URL of the repository (or Github `owner/repo`) to link to
 - `id` (*string*) - ID of site to link to
 - `name` (*string*) - Name of site to link to
 - `debug` (*boolean*) - Print debugging information
@@ -31,6 +32,7 @@ netlify link
 netlify link
 netlify link --id 123-123-123-123
 netlify link --name my-site-name
+netlify link --git-remote-url https://github.com/vibecoder/my-unicorn.git
 ```
 
 

docs/index.md

@@ -38,6 +38,10 @@ Manage objects in Netlify Blobs
 
 Build on your local machine
 
+### [clone](/commands/clone)
+
+Clone a remote repository and link it to an existing site on Netlify
+
 ### [completion](/commands/completion)
 
 Generate shell completion script

src/commands/clone/clone.ts

@@ -0,0 +1,78 @@
+import inquirer from 'inquirer'
+
+import { normalizeRepoUrl } from '../../utils/normalize-repo-url.js'
+import { chalk, logAndThrowError, log } from '../../utils/command-helpers.js'
+import { runGit } from '../../utils/run-git.js'
+import type BaseCommand from '../base-command.js'
+import { link } from '../link/link.js'
+import type { CloneOptionValues } from './option_values.js'
+import { startSpinner } from '../../lib/spinner.js'
+
+const getTargetDir = async (defaultDir: string): Promise<string> => {
+  const { selectedDir } = await inquirer.prompt<{ selectedDir: string }>([
+    {
+      type: 'input',
+      name: 'selectedDir',
+      message: 'Where should we clone the repository?',
+      default: defaultDir,
+    },
+  ])
+
+  return selectedDir
+}
+
+const cloneRepo = async (repoUrl: string, targetDir: string, debug: boolean): Promise<void> => {
+  try {
+    await runGit(['clone', repoUrl, targetDir], !debug)
+  } catch (error) {
+    throw new Error(`Failed to clone repository: ${error instanceof Error ? error.message : error?.toString() ?? ''}`)
+  }
+}
+
+export const clone = async (
+  options: CloneOptionValues,
+  command: BaseCommand,
+  args: { repo: string; targetDir?: string },
+) => {
+  await command.authenticate()
+
+  const { repoUrl, httpsUrl, repoName } = normalizeRepoUrl(args.repo)
+
+  const targetDir = args.targetDir ?? (await getTargetDir(`./${repoName}`))
+
+  const cloneSpinner = startSpinner({ text: `Cloning repository to ${chalk.cyan(targetDir)}` })
+  try {
+    await cloneRepo(repoUrl, targetDir, options.debug ?? false)
+  } catch (error) {
+    return logAndThrowError(error)
+  }
+  cloneSpinner.success(`Cloned repository to ${chalk.cyan(targetDir)}`)
+
+  command.workingDir = targetDir
+  // TODO(serhalp): This shouldn't be necessary but `getPathInProject` does not take
+  // `command.workingDir` into account. Carefully fix this and remove this line.
+  process.chdir(targetDir)
+
+  const { id, name, ...globalOptions } = options
+  const linkOptions = {
+    ...globalOptions,
+    id,
+    name,
+    // Use the normalized HTTPS URL as the canonical git URL for linking to ensure
+    // we have a consistent URL format for looking up sites.
+    gitRemoteUrl: httpsUrl,
+  }
+  await link(linkOptions, command)
+
+  log()
+  log(chalk.green('✔ Your project is ready to go!'))
+  log(`→ Next, enter your project directory using ${chalk.cyanBright(`cd ${targetDir}`)}`)
+  log()
+  log(`→ You can now run other ${chalk.cyanBright('netlify')} CLI commands in this directory`)
+  log(`→ To build and deploy your site: ${chalk.cyanBright('netlify deploy')}`)
+  if (command.netlify.config.dev?.command) {
+    log(`→ To run your dev server: ${chalk.cyanBright(command.netlify.config.dev.command)}`)
+  }
+  log(`→ To see all available commands: ${chalk.cyanBright('netlify help')}`)
+  log()
+}

src/commands/clone/index.ts

@@ -0,0 +1,36 @@
+import terminalLink from 'terminal-link'
+
+import type BaseCommand from '../base-command.js'
+import type { CloneOptionValues } from './option_values.js'
+
+export const createCloneCommand = (program: BaseCommand) =>
+  program
+    .command('clone')
+    .description(
+      `Clone a remote repository and link it to an existing site on Netlify
+Use this command when the existing Netlify site is already configured to deploy from the existing repo.
+
+If you specify a target directory, the repo will be cloned into that directory. By default, a directory will be created with the name of the repo.
+
+To specify a site, use --id or --name. By default, the Netlify site to link will be automatically detected if exactly one site found is found with a matching git URL. If we cannot find such a site, you will be interactively prompted to select one.`,
+    )
+    .argument('<repo>', 'URL of the repository to clone or Github `owner/repo` (required)')
+    .argument('[targetDir]', 'directory in which to clone the repository - will be created if it does not exist')
+    .option('--id <id>', 'ID of existing Netlify site to link to')
+    .option('--name <name>', 'Name of existing Netlify site to link to')
+    .addExamples([
+      'netlify clone vibecoder/next-unicorn',
+      'netlify clone https://github.com/vibecoder/next-unicorn.git',
+      'netlify clone git@github.com:vibecoder/next-unicorn.git',
+      'netlify clone vibecoder/next-unicorn ./next-unicorn-shh-secret',
+      'netlify clone --id 123-123-123-123 vibecoder/next-unicorn',
+      'netlify clone --name my-site-name vibecoder/next-unicorn',
+    ])
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/cli/get-started/#link-and-unlink-sites'
+      return `For more information about linking sites, see ${terminalLink(docsUrl, docsUrl)}\n`
+    })
+    .action(async (repo: string, targetDir: string | undefined, options: CloneOptionValues, command: BaseCommand) => {
+      const { clone } = await import('./clone.js')
+      await clone(options, command, { repo, targetDir })
+    })

src/commands/clone/option_values.ts

@@ -0,0 +1,9 @@
+import type { BaseOptionValues } from '../base-command.js'
+
+export type CloneOptionValues = BaseOptionValues & {
+  // NOTE(serhalp): Think this would be better off as `siteId`? Beware, here be dragons.
+  // There's some magical global state mutation dance going on somewhere when you call
+  // an option `--site-id`. Good luck, friend.
+  id?: string | undefined
+  name?: string | undefined
+}

src/commands/link/index.ts

@@ -1,7 +1,7 @@
-import { OptionValues } from 'commander'
 import terminalLink from 'terminal-link'
 
 import BaseCommand from '../base-command.js'
+import type { LinkOptionValues } from './option_values.js'
 
 export const createLinkCommand = (program: BaseCommand) =>
   program
@@ -10,14 +10,20 @@ export const createLinkCommand = (program: BaseCommand) =>
     .option('--id <id>', 'ID of site to link to')
     .option('--name <name>', 'Name of site to link to')
     .option('--git-remote-name <name>', 'Name of Git remote to use. e.g. "origin"')
-    .addExamples(['netlify link', 'netlify link --id 123-123-123-123', 'netlify link --name my-site-name'])
+    .option('--git-remote-url <name>', 'URL of the repository (or Github `owner/repo`) to link to')
+    .addExamples([
+      'netlify link',
+      'netlify link --id 123-123-123-123',
+      'netlify link --name my-site-name',
+      'netlify link --git-remote-url https://github.com/vibecoder/my-unicorn.git',
+    ])
     .addHelpText('after', () => {
       const docsUrl = 'https://docs.netlify.com/cli/get-started/#link-and-unlink-sites'
       return `
 For more information about linking sites, see ${terminalLink(docsUrl, docsUrl)}
 `
     })
-    .action(async (options: OptionValues, command: BaseCommand) => {
+    .action(async (options: LinkOptionValues, command: BaseCommand) => {
       const { link } = await import('./link.js')
       await link(options, command)
     })