feat: add site search and improve non-interactive linking (#8127)

# Improve `netlify link` and Add `netlify sites:search` for
Non-Interactive Environments

## Overview

This PR improves the Netlify CLI's behavior in non-interactive
environments (CI/CD, scripts, AI agents) by fixing `netlify link`
hanging issues and introducing a new `sites:search` command for site
discovery.

## Changes

### 1. 🔍 New Command: `netlify sites:search`

Added a new command for searching projects by name, making site
discovery easier for both users and automation tools.

**Usage:**
```bash
netlify sites:search my-project
netlify sites:search "partial name" --json
```

**Features:**
- Searches by full or partial project name
- Returns matching projects with ID, URL, repo, and account info
- Supports `--json` flag for programmatic use
- Works seamlessly in CI/CD environments

### 2. 🔗 Fixed `netlify link` Non-Interactive Behavior

Previously, `netlify link` would hang indefinitely when run without
options in CI/CD environments. Now it provides helpful guidance instead.

**Before:**
```bash
# In CI/CD:
netlify link
# ❌ Hangs trying to prompt user interactively
```

**After:**
```bash
# In CI/CD:
netlify link
# ✅ Error: No project specified. In non-interactive mode, you must specify how to link:
#
# Link by project ID:
#   netlify link --id <project-id>
#
# Link by project name:
#   netlify link --name <project-name>
#
# To search for projects:
#   netlify sites:search <search-term>
```

**Updated error messages to guide users:**
- When no site found by name → suggests `sites:search` and `link --id`
- When no site found by git remote → suggests `sites:search` and manual
linking options
- When no options provided in CI/CD → shows all available linking
methods

## Example Scenarios

### Scenario 1: AI Agent Linking a Project

**Before:**
```bash
Agent: netlify link
CLI: [hangs waiting for interactive input]
Agent: [timeout or confusion]
```

**After:**
```bash
Agent: netlify link
CLI: Error with helpful guidance showing all options
Agent: netlify sites:search my-project --json
CLI: [{"id":"site-123","name":"my-project",...}]
Agent: netlify link --id site-123
CLI: ✓ Linked to my-project
```

### Scenario 2: Agent Searching for a Site

**Before:**
```bash
Agent: [tries to use undocumented API or link --name with guessing]
CLI: [may link to wrong site or fail]
```

**After:**
```bash
Agent: netlify sites:search "customer-portal" --json
CLI: [
  {"id":"site-1","name":"customer-portal-staging",...},
  {"id":"site-2","name":"customer-portal-prod",...}
]
Agent: [can now make informed decision about which site to use]
```

### Scenario 3: CI/CD Script Needing to Link

**Before:**
```bash
# CI/CD script without knowing site ID:
netlify link
# ❌ Hangs indefinitely, pipeline fails
```

**After:**
```bash
# CI/CD script can discover and link:
SITE_ID=$(netlify sites:search "$PROJECT_NAME" --json | jq -r '.[0].id')
netlify link --id "$SITE_ID"
# ✅ Successfully linked
```

## Testing

### New Tests Added
- **`sites:search`**: 6 tests covering search, JSON output, empty
results, non-interactive mode
- **`link`**: 3 tests for non-interactive error handling

### Test Coverage
- ✅ All tests passing
- ✅ Explicit CI/CD environment tests (`CI=true`, `isTTY=false`)
- ✅ Verified no hanging in non-interactive scenarios
- ✅ Verified helpful error messages appear correctly

### Documentation
- ✅ Generated command documentation for `sites:search`
- ✅ Updated help snapshots
- ✅ All commands properly documented with examples

## Breaking Changes

None. All changes are backward compatible and only add features or
improve error handling.

## Related Issues

Addresses common issues with:
- CLI hanging in CI/CD environments
- AI agents unable to discover and link sites programmatically
- Unclear guidance when commands fail in non-interactive mode

---

**Summary:** This PR makes the Netlify CLI more robust for automated
environments by preventing `netlify link` from hanging in CI/CD and
providing a new `sites:search` command for programmatic site discovery.

---------

Co-authored-by: Sean Roberts <sean.roberts@netlify.com>

Author: sean-roberts

docs/commands/sites.md

@@ -28,6 +28,7 @@ netlify sites
 | [`sites:create`](/commands/sites#sitescreate) | Create an empty project (advanced)  |
 | [`sites:delete`](/commands/sites#sitesdelete) | Delete a project  |
 | [`sites:list`](/commands/sites#siteslist) | List all projects you have access to  |
+| [`sites:search`](/commands/sites#sitessearch) | Search for projects by name  |
 
 
 **Examples**
@@ -109,6 +110,35 @@ netlify sites:list
 - `debug` (*boolean*) - Print debugging information
 - `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
 
+---
+## `sites:search`
+
+Search for projects by name
+
+**Usage**
+
+```bash
+netlify sites:search
+```
+
+**Arguments**
+
+- search-term - Full or partial project name to search for
+
+**Flags**
+
+- `filter` (*string*) - For monorepos, specify the name of the application to run the command in
+- `json` (*boolean*) - Output project data as JSON
+- `debug` (*boolean*) - Print debugging information
+- `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
+
+**Examples**
+
+```bash
+netlify sites:search my-project
+netlify sites:search "partial name" --json
+```
+
 ---
 
 <!-- AUTO-GENERATED-CONTENT:END -->

docs/index.md

@@ -175,6 +175,7 @@ Handle various project operations
 | [`sites:create`](/commands/sites#sitescreate) | Create an empty project (advanced)  |
 | [`sites:delete`](/commands/sites#sitesdelete) | Delete a project  |
 | [`sites:list`](/commands/sites#siteslist) | List all projects you have access to  |
+| [`sites:search`](/commands/sites#sitessearch) | Search for projects by name  |
 
 
 ### [status](/commands/status)

src/commands/link/link.ts

@@ -9,6 +9,7 @@ import { startSpinner } from '../../lib/spinner.js'
 import { chalk, logAndThrowError, exit, log, APIError, netlifyCommand } from '../../utils/command-helpers.js'
 import { ensureNetlifyIgnore } from '../../utils/gitignore.js'
 import getRepoData from '../../utils/get-repo-data.js'
+import { isInteractive } from '../../utils/scripted-commands.js'
 import { track } from '../../utils/telemetry/index.js'
 import type { SiteInfo } from '../../utils/types.js'
 import BaseCommand from '../base-command.js'
@@ -39,7 +40,14 @@ const findSiteByRepoUrl = async (api: NetlifyAPI, repoUrl: string): Promise<Site
 
 Double check you are in the correct working directory and a remote origin repo is configured.
 
-Run ${chalk.cyanBright('git remote -v')} to see a list of your git remotes.`)
+Run ${chalk.cyanBright('git remote -v')} to see a list of your git remotes.
+
+To link manually:
+  ${chalk.cyanBright(`${netlifyCommand()} link --id <project-id>`)}
+  ${chalk.cyanBright(`${netlifyCommand()} link --name <project-name>`)}
+
+To search for projects:
+  ${chalk.cyanBright(`${netlifyCommand()} sites:search <search-term>`)}`)
 
     return exit(1)
   }
@@ -144,8 +152,14 @@ const linkPrompt = async (command: BaseCommand, options: LinkOptionValues): Prom
       if (!matchingSites || matchingSites.length === 0) {
         return logAndThrowError(`No project names found containing '${searchTerm}'.
 
-Run ${chalk.cyanBright(`${netlifyCommand()} link`)} again to try a new search,
-or run ${chalk.cyanBright(`npx ${netlifyCommand()} sites:create`)} to create a project.`)
+To search for projects:
+  ${chalk.cyanBright(`${netlifyCommand()} sites:search <search-term>`)}
+
+To link by project ID:
+  ${chalk.cyanBright(`${netlifyCommand()} link --id <project-id>`)}
+
+To create a new project:
+  ${chalk.cyanBright(`${netlifyCommand()} sites:create`)}`)
       }
 
       if (matchingSites.length > 1) {
@@ -326,7 +340,13 @@ export const link = async (options: LinkOptionValues, command: BaseCommand) => {
     }
 
     if (results.length === 0) {
-      return logAndThrowError(new Error(`No projects found named ${options.name}`))
+      return logAndThrowError(`No projects found named ${options.name}.
+
+To search for projects:
+  ${chalk.cyanBright(`${netlifyCommand()} sites:search ${options.name}`)}
+
+To link by project ID:
+  ${chalk.cyanBright(`${netlifyCommand()} link --id <project-id>`)}`)
     }
 
     const matchingSiteData = results.find((site: SiteInfo) => site.name === options.name) || results[0]
@@ -350,6 +370,25 @@ export const link = async (options: LinkOptionValues, command: BaseCommand) => {
       kind: 'byRepoUrl',
     })
   } else {
+    if (!isInteractive()) {
+      return logAndThrowError(`No project specified. In non-interactive mode, you must specify how to link:
+
+Link by project ID:
+  ${chalk.cyanBright(`${netlifyCommand()} link --id <project-id>`)}
+
+Link by project name:
+  ${chalk.cyanBright(`${netlifyCommand()} link --name <project-name>`)}
+
+Link by git remote URL:
+  ${chalk.cyanBright(`${netlifyCommand()} link --gitRemoteUrl <url>`)}
+
+To search for projects:
+  ${chalk.cyanBright(`${netlifyCommand()} sites:search <search-term>`)}
+
+To list all projects:
+  ${chalk.cyanBright(`${netlifyCommand()} sites:list`)}`)
+    }
+
     newSiteData = await linkPrompt(command, options)
   }
   // FIXME(serhalp): All the cases above except one (look up by site name) end up *returning*

src/commands/sites/sites-search.ts

@@ -0,0 +1,62 @@
+import { OptionValues } from 'commander'
+
+import { listSites } from '../../lib/api.js'
+import { startSpinner, stopSpinner } from '../../lib/spinner.js'
+import { chalk, log, logJson } from '../../utils/command-helpers.js'
+import BaseCommand from '../base-command.js'
+
+export const sitesSearch = async (searchTerm: string, options: OptionValues, command: BaseCommand) => {
+  const { api } = command.netlify
+
+  await command.authenticate()
+
+  let spinner
+  if (!options.json) {
+    spinner = startSpinner({ text: `Searching for projects matching '${searchTerm}'` })
+  }
+
+  const sites = await listSites({ api, options: { name: searchTerm, filter: 'all' } })
+
+  if (spinner) {
+    stopSpinner({ spinner })
+  }
+
+  if (sites.length === 0) {
+    if (options.json) {
+      logJson([])
+      return
+    }
+
+    log()
+    log(chalk.yellow(`No projects found matching '${searchTerm}'`))
+    log()
+    return
+  }
+
+  if (options.json) {
+    const redactedSites = sites.map((site) => {
+      if (site.build_settings?.env) {
+        delete site.build_settings.env
+      }
+      return site
+    })
+    logJson(redactedSites)
+    return
+  }
+
+  log()
+  log(`Found ${chalk.greenBright(sites.length)} project${sites.length === 1 ? '' : 's'} matching '${searchTerm}':`)
+  log()
+
+  sites.forEach((site) => {
+    log(`${chalk.greenBright(site.name)} - ${chalk.dim(site.id)}`)
+    log(`  ${chalk.whiteBright.bold('url:')}  ${chalk.yellowBright(site.ssl_url)}`)
+    if (site.build_settings?.repo_url) {
+      log(`  ${chalk.whiteBright.bold('repo:')} ${chalk.white(site.build_settings.repo_url)}`)
+    }
+    if (site.account_name) {
+      log(`  ${chalk.whiteBright.bold('account:')} ${chalk.white(site.account_name)}`)
+    }
+    log(`─────────────────────────────────────────────────`)
+  })
+}

src/commands/sites/sites.ts

@@ -47,6 +47,17 @@ export const createSitesCommand = (program: BaseCommand) => {
       await sitesList(options, command)
     })
 
+  program
+    .command('sites:search')
+    .description('Search for projects by name')
+    .argument('<search-term>', 'Full or partial project name to search for')
+    .option('--json', 'Output project data as JSON')
+    .addExamples(['netlify sites:search my-project', 'netlify sites:search "partial name" --json'])
+    .action(async (searchTerm: string, options: OptionValues, command: BaseCommand) => {
+      const { sitesSearch } = await import('./sites-search.js')
+      await sitesSearch(searchTerm, options, command)
+    })
+
   program
     .command('sites:delete')
     .description('Delete a project\nThis command will permanently delete the project on Netlify. Use with caution.')

tests/integration/commands/link/link.test.ts

@@ -150,3 +150,90 @@ describe('link command with multiple projects', () => {
     })
   })
 })
+
+describe('link command non-interactive mode', () => {
+  test('should error with helpful message when no options provided in non-interactive mode', async (t) => {
+    await withSiteBuilder(t, async (builder) => {
+      await builder.build()
+
+      await withMockApi(
+        [],
+        async ({ apiUrl }) => {
+          try {
+            await callCli(['link'], {
+              ...getCLIOptions({ builder, apiUrl, env: { NETLIFY_SITE_ID: '', CI: 'true' } }),
+            })
+            expect.fail('Should have thrown an error')
+          } catch (error_) {
+            const errorMessage = (error_ as Error).message
+            expect(errorMessage).toContain('No project specified')
+            expect(errorMessage).toContain('link --id')
+            expect(errorMessage).toContain('link --name')
+            expect(errorMessage).toContain('sites:search')
+          }
+        },
+        true,
+      )
+    })
+  })
+
+  test('should error with helpful message when site not found by name', async (t) => {
+    const routes = [
+      {
+        path: 'sites',
+        response: [],
+      },
+    ]
+
+    await withSiteBuilder(t, async (builder) => {
+      await builder.build()
+
+      await withMockApi(
+        routes,
+        async ({ apiUrl }) => {
+          await expect(
+            callCli(
+              ['link', '--name', 'nonexistent-site'],
+              getCLIOptions({ builder, apiUrl, env: { NETLIFY_SITE_ID: '' } }),
+            ),
+          ).rejects.toThrow(/No projects found|sites:search/)
+        },
+        true,
+      )
+    })
+  })
+
+  test('should error with helpful message when site not found by git remote', async (t) => {
+    const routes = [
+      {
+        path: 'sites',
+        response: [
+          {
+            id: 'different-site-id',
+            name: 'different-site',
+            build_settings: {
+              repo_url: 'https://github.com/other/repo',
+            },
+          },
+        ],
+      },
+    ]
+
+    await withSiteBuilder(t, async (builder) => {
+      await builder.withGit().build()
+
+      await withMockApi(
+        routes,
+        async ({ apiUrl }) => {
+          await expect(
+            callCli(
+              ['link', '--git-remote-url', 'https://github.com/test/repo'],
+              getCLIOptions({ builder, apiUrl, env: { NETLIFY_SITE_ID: '' } }),
+            ),
+          ).rejects.toThrow(/No matching project found|sites:search/)
+        },
+        true,
+      )
+    })
+  })
+})