feat: link out to relevant Netlify docs in command help output (#7254)

serhalp · mrstork · web-flow · commit 1978faf6ca59 · 2025-05-02T21:51:46.000Z
* feat: link out to relevant Netlify platform from cmd help

* fix: fix "check out" typo in some messages

* feat: polish and improve main help text

- always show the Netlify CLI header, not just the bare `netlify` case (there is also
  `netlify help` and `netlify --help`, which was otherwise identical)
- use commander API instead of custom logging
- use more consistent branding
- change CLI getting started landing page
- move the links to the bottom
- add link to main Netlify docs

* refactor: fix some suppressed no-unused-vars errors

* test: fix e2e test help output assertion

---------

Co-authored-by: Mateusz Bocian &lt;mrstork@users.noreply.github.com&gt;
diff --git a/docs/commands/api.md b/docs/commands/api.md
@@ -10,7 +10,7 @@ The `api` command will let you call any [Netlify open API methods](https://open-
 
 <!-- AUTO-GENERATED-CONTENT:START (GENERATE_COMMANDS_DOCS) -->
 Run any Netlify API method
-For more information on available methods checkout https://open-api.netlify.com/ or run 'netlify api --list'
+For more information on available methods check out https://open-api.netlify.com/ or run 'netlify api --list'
 
 **Usage**
 
diff --git a/e2e/install.e2e.ts b/e2e/install.e2e.ts
@@ -176,7 +176,9 @@ describe.each(tests)('%s → installs the cli and runs the help command without
     const binary = path.resolve(path.join(cwd, `./node_modules/.bin/netlify${platform() === 'win32' ? '.cmd' : ''}`))
     const { stdout } = await execa(binary, ['help'], { cwd })
 
-    expect(stdout.trim(), `Help command does not start with 'VERSION':\n\n${stdout}`).toMatch(/^VERSION/)
+    expect(stdout.trim(), `Help command does not start with '⬥ Netlify CLI'\\n\\nVERSION: ${stdout}`).toMatch(
+      /^⬥ Netlify CLI\n\nVERSION/,
+    )
     expect(stdout, `Help command does not include 'netlify-cli/${pkg.version}':\n\n${stdout}`).toContain(
       `netlify-cli/${pkg.version}`,
     )
diff --git a/eslint_temporary_suppressions.js b/eslint_temporary_suppressions.js
@@ -105,12 +105,6 @@ export default [
       '@typescript-eslint/no-unsafe-assignment': 'off',
     },
   },
-  {
-    files: ['src/commands/completion/index.ts'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
-    },
-  },
   {
     files: ['src/commands/deploy/deploy.ts'],
     rules: {
@@ -196,7 +190,6 @@ export default [
   {
     files: ['src/commands/env/env-unset.ts'],
     rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/no-unsafe-assignment': 'off',
       '@typescript-eslint/no-unsafe-member-access': 'off',
       '@typescript-eslint/no-unsafe-call': 'off',
@@ -224,7 +217,6 @@ export default [
       '@typescript-eslint/no-unnecessary-condition': 'off',
       '@typescript-eslint/restrict-template-expressions': 'off',
       'n/no-process-exit': 'off',
-      '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/prefer-optional-chain': 'off',
       '@typescript-eslint/await-thenable': 'off',
       '@typescript-eslint/no-confusing-void-expression': 'off',
@@ -250,24 +242,12 @@ export default [
       '@typescript-eslint/no-unnecessary-condition': 'off',
     },
   },
-  {
-    files: ['src/commands/init/index.ts'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
-    },
-  },
   {
     files: ['src/commands/init/init.ts'],
     rules: {
       '@typescript-eslint/no-unsafe-assignment': 'off',
     },
   },
-  {
-    files: ['src/commands/link/index.ts'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
-    },
-  },
   {
     files: ['src/commands/link/link.ts'],
     rules: {
@@ -280,12 +260,6 @@ export default [
       '@typescript-eslint/prefer-optional-chain': 'off',
     },
   },
-  {
-    files: ['src/commands/logout/logout.ts'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
-    },
-  },
   {
     files: ['src/commands/logs/build.ts'],
     rules: {
@@ -294,7 +268,6 @@ export default [
       '@typescript-eslint/no-unsafe-assignment': 'off',
       '@typescript-eslint/restrict-template-expressions': 'off',
       '@typescript-eslint/no-unsafe-call': 'off',
-      '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/prefer-nullish-coalescing': 'off',
       '@typescript-eslint/no-unsafe-argument': 'off',
     },
@@ -334,12 +307,6 @@ export default [
       '@typescript-eslint/no-unsafe-argument': 'off',
     },
   },
-  {
-    files: ['src/commands/open/open-site.ts'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
-    },
-  },
   {
     files: ['src/commands/recipes/common.ts'],
     rules: {
@@ -414,20 +381,17 @@ export default [
     rules: {
       '@typescript-eslint/restrict-template-expressions': 'off',
       '@typescript-eslint/no-unsafe-return': 'off',
-      '@typescript-eslint/no-unused-vars': 'off',
     },
   },
   {
     files: ['src/commands/status/status-hooks.ts'],
     rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/no-unsafe-member-access': 'off',
     },
   },
   {
     files: ['src/commands/switch/switch.ts'],
     rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/no-unsafe-argument': 'off',
       '@typescript-eslint/no-unsafe-assignment': 'off',
       '@typescript-eslint/restrict-template-expressions': 'off',
@@ -442,7 +406,6 @@ export default [
   {
     files: ['src/commands/unlink/unlink.ts'],
     rules: {
-      '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/no-unnecessary-condition': 'off',
       '@typescript-eslint/prefer-optional-chain': 'off',
     },
diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts
@@ -7,7 +7,7 @@ export const createApiCommand = (program: BaseCommand) =>
     .argument('[apiMethod]', 'Open API method to run')
     .description(
       `Run any Netlify API method
-For more information on available methods checkout https://open-api.netlify.com/ or run '${chalk.grey(
+For more information on available methods check out https://open-api.netlify.com/ or run '${chalk.grey(
         'netlify api --list',
       )}'`,
     )
diff --git a/src/commands/blobs/blobs.ts b/src/commands/blobs/blobs.ts
@@ -1,4 +1,5 @@
 import { OptionValues } from 'commander'
+import terminalLink from 'terminal-link'
 
 import requiresSiteInfo from '../../utils/hooks/requires-site-info.js'
 import BaseCommand from '../base-command.js'
@@ -84,6 +85,12 @@ export const createBlobsCommand = (program: BaseCommand) => {
     .command('blobs')
     .alias('blob')
     .description(`Manage objects in Netlify Blobs`)
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/blobs/overview/'
+      return `
+For more information about Netlify Blobs, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .addExamples([
       'netlify blobs:get my-store my-key',
       'netlify blobs:set my-store my-key This will go in a blob',
diff --git a/src/commands/build/index.ts b/src/commands/build/index.ts
@@ -1,5 +1,7 @@
 import process from 'process'
 
+import terminalLink from 'terminal-link'
+
 import { normalizeContext } from '../../utils/env/index.js'
 import BaseCommand from '../base-command.js'
 
@@ -20,6 +22,12 @@ export const createBuildCommand = (program: BaseCommand) =>
       'netlify build --context deploy-preview # Build with env var values from deploy-preview context',
       'netlify build --context branch:feat/make-it-pop # Build with env var values from the feat/make-it-pop branch context or branch-deploy context',
     ])
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/configure-builds/overview/'
+      return `
+For more information about Netlify builds, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(async (options, command) => {
       const { build } = await import('./build.js')
       await build(options, command)
diff --git a/src/commands/completion/index.ts b/src/commands/completion/index.ts
@@ -26,7 +26,7 @@ export const createCompletionCommand = (program: BaseCommand) => {
     .command('completion')
     .description('Generate shell completion script\nRun this command to see instructions for your shell.')
     .addExamples(['netlify completion:install'])
-    .action((options: OptionValues, command: BaseCommand) => {
+    .action((_options: OptionValues, command: BaseCommand) => {
       command.help()
     })
 }
diff --git a/src/commands/deploy/index.ts b/src/commands/deploy/index.ts
@@ -1,6 +1,7 @@
 import { env } from 'process'
 
 import { Option } from 'commander'
+import terminalLink from 'terminal-link'
 
 import BaseCommand from '../base-command.js'
 import { chalk, logAndThrowError, warn } from '../../utils/command-helpers.js'
@@ -143,6 +144,12 @@ Support for package.json's main field, and intrinsic index.js entrypoints are co
       'netlify deploy --trigger',
       'netlify deploy --context deploy-preview',
     ])
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/site-deploys/overview/'
+      return `
+For more information about Netlify deploys, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(async (options: DeployOptionValues, command: BaseCommand) => {
       if (options.build && command.getOptionValueSource('build') === 'cli') {
         warn(
diff --git a/src/commands/dev/index.ts b/src/commands/dev/index.ts
@@ -1,4 +1,5 @@
 import { Option, type OptionValues } from 'commander'
+import terminalLink from 'terminal-link'
 
 import { BANG, chalk } from '../../utils/command-helpers.js'
 import { normalizeContext } from '../../utils/env/index.js'
@@ -105,6 +106,12 @@ export const createDevCommand = (program: BaseCommand) => {
       'netlify dev --edge-inspect-brk=127.0.0.1:9229',
       'BROWSER=none netlify dev # disable browser auto opening',
     ])
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/cli/local-development/'
+      return `
+For more information about Netlify local development, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(async (options: OptionValues, command: BaseCommand) => {
       const { dev } = await import('./dev.js')
       await dev(options, command)
diff --git a/src/commands/env/env-unset.ts b/src/commands/env/env-unset.ts
@@ -1,6 +1,6 @@
 import { OptionValues } from 'commander'
 
-import { chalk, log, logJson, exit } from '../../utils/command-helpers.js'
+import { chalk, log, logJson } from '../../utils/command-helpers.js'
 import { SUPPORTED_CONTEXTS, translateFromEnvelopeToMongo } from '../../utils/env/index.js'
 import { promptOverwriteEnvVariable } from '../../utils/prompts/env-unset-prompts.js'
 import BaseCommand from '../base-command.js'
diff --git a/src/commands/env/env.ts b/src/commands/env/env.ts
@@ -1,4 +1,5 @@
 import { OptionValues, Option } from 'commander'
+import terminalLink from 'terminal-link'
 
 import { normalizeContext } from '../../utils/env/index.js'
 import BaseCommand from '../base-command.js'
@@ -160,5 +161,11 @@ export const createEnvCommand = (program: BaseCommand) => {
       'netlify env:import fileName',
       'netlify env:clone --to <to-site-id>',
     ])
+    .addHelpText('afterAll', () => {
+      const docsUrl = 'https://docs.netlify.com/configure-builds/environment-variables/'
+      return `
+For more information about environment variables on Netlify, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(env)
 }
diff --git a/src/commands/functions/functions-create.ts b/src/commands/functions/functions-create.ts
@@ -496,7 +496,7 @@ const scaffoldFromTemplate = async function (command, options, argumentName, fun
     options.url = chosenUrl.trim()
     try {
       await downloadFromURL(command, options, argumentName, functionsDir)
-    } catch (error_) {
+    } catch {
       return logAndThrowError(`$${NETLIFYDEVERR} Error downloading from URL: ${options.url}`)
     }
   } else if (chosenTemplate === 'report') {
diff --git a/src/commands/functions/functions.ts b/src/commands/functions/functions.ts
@@ -1,4 +1,5 @@
 import type { OptionValues } from 'commander'
+import terminalLink from 'terminal-link'
 
 import { chalk } from '../../utils/command-helpers.js'
 import requiresSiteInfo from '../../utils/hooks/requires-site-info.js'
@@ -119,5 +120,11 @@ The ${name} command will help you manage the functions in this site`,
       'netlify functions:create --name function-xyz',
       'netlify functions:build --functions build/to/directory --src source/directory',
     ])
+    .addHelpText('afterAll', () => {
+      const docsUrl = 'https://docs.netlify.com/functions/overview/'
+      return `
+For more information about Netlify Functions, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(functions)
 }
diff --git a/src/commands/init/index.ts b/src/commands/init/index.ts
@@ -1,4 +1,5 @@
-import { Option, OptionValues } from 'commander'
+import { OptionValues } from 'commander'
+import terminalLink from 'terminal-link'
 
 import BaseCommand from '../base-command.js'
 
@@ -10,6 +11,12 @@ export const createInitCommand = (program: BaseCommand) =>
     )
     .option('-m, --manual', 'Manually configure a git remote for CI')
     .option('--git-remote-name <name>', 'Name of Git remote to use. e.g. "origin"')
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/cli/get-started/'
+      return `
+For more information about getting started with Netlify CLI, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(async (options: OptionValues, command: BaseCommand) => {
       const { init } = await import('./init.js')
       await init(options, command)
diff --git a/src/commands/init/init.ts b/src/commands/init/init.ts
@@ -102,7 +102,7 @@ It is recommended that you initialize a site that has a remote repository in Git
 
 This will allow for Netlify Continuous deployment to build branch & PR previews.
 
-For more details on Netlify CI checkout the docs: http://bit.ly/2N0Jhy5
+For more details on Netlify CI check out the docs: http://bit.ly/2N0Jhy5
 `)
   if (error === "Couldn't find origin url") {
     log(`Unable to find a remote origin URL. Please add a git remote.
diff --git a/src/commands/link/index.ts b/src/commands/link/index.ts
@@ -1,4 +1,5 @@
-import { Option, OptionValues } from 'commander'
+import { OptionValues } from 'commander'
+import terminalLink from 'terminal-link'
 
 import BaseCommand from '../base-command.js'
 
@@ -10,6 +11,12 @@ export const createLinkCommand = (program: BaseCommand) =>
     .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'])
+    .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) => {
       const { link } = await import('./link.js')
       await link(options, command)
diff --git a/src/commands/login/index.ts b/src/commands/login/index.ts
@@ -1,4 +1,5 @@
 import { OptionValues } from 'commander'
+import terminalLink from 'terminal-link'
 
 import BaseCommand from '../base-command.js'
 
@@ -10,6 +11,12 @@ export const createLoginCommand = (program: BaseCommand) =>
 Opens a web browser to acquire an OAuth token.`,
     )
     .option('--new', 'Login to new Netlify account')
+    .addHelpText('after', () => {
+      const docsUrl = 'https://docs.netlify.com/cli/get-started/#authentication'
+      return `
+For more information about Netlify authentication, see ${terminalLink(docsUrl, docsUrl)}
+`
+    })
     .action(async (options: OptionValues, command: BaseCommand) => {
       const { login } = await import('./login.js')
       await login(options, command)
diff --git a/src/commands/logout/logout.ts b/src/commands/logout/logout.ts
@@ -4,7 +4,7 @@ import { exit, getToken, log } from '../../utils/command-helpers.js'
 import { track } from '../../utils/telemetry/index.js'
 import BaseCommand from '../base-command.js'
 
-export const logout = async (options: OptionValues, command: BaseCommand) => {
+export const logout = async (_options: OptionValues, command: BaseCommand) => {
   const [accessToken, location] = await getToken()
 
   if (!accessToken) {
diff --git a/src/commands/logs/build.ts b/src/commands/logs/build.ts
@@ -32,7 +32,7 @@ export function getName({ deploy, userId }: { deploy: any; userId: string }) {
   return `(${deploy.id.slice(0, 7)}) ${normalisedName}`
 }
 
-export const logsBuild = async (options: OptionValues, command: BaseCommand) => {
+export const logsBuild = async (_options: OptionValues, command: BaseCommand) => {
   await command.authenticate()
   const client = command.netlify.api
   const { site } = command.netlify
diff --git a/src/commands/main.ts b/src/commands/main.ts
diff --git a/src/commands/open/open-site.ts b/src/commands/open/open-site.ts
diff --git a/src/commands/sites/sites.ts b/src/commands/sites/sites.ts
diff --git a/src/commands/switch/switch.ts b/src/commands/switch/switch.ts
diff --git a/src/commands/unlink/index.ts b/src/commands/unlink/index.ts
diff --git a/src/commands/unlink/unlink.ts b/src/commands/unlink/unlink.ts
diff --git a/tests/integration/commands/help/__snapshots__/help.test.ts.snap b/tests/integration/commands/help/__snapshots__/help.test.ts.snap

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ export const createApiCommand = (program: BaseCommand) =>`
`7`	`7`	`.argument('[apiMethod]', 'Open API method to run')`
`8`	`8`	`.description(`
`9`	`9`	`Run any Netlify API method
`10`		`-For more information on available methods checkout https://open-api.netlify.com/ or run '${chalk.grey(`
	`10`	`+For more information on available methods check out https://open-api.netlify.com/ or run '${chalk.grey(`
`11`	`11`	`'netlify api --list',`
`12`	`12`	)}'`,
`13`	`13`	`)`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ export const createCompletionCommand = (program: BaseCommand) => {`
`26`	`26`	`.command('completion')`
`27`	`27`	`.description('Generate shell completion script\nRun this command to see instructions for your shell.')`
`28`	`28`	`.addExamples(['netlify completion:install'])`
`29`		`- .action((options: OptionValues, command: BaseCommand) => {`
	`29`	`+ .action((_options: OptionValues, command: BaseCommand) => {`
`30`	`30`	`command.help()`
`31`	`31`	`})`
`32`	`32`	`}`