---

name: cli-ux-polish description: Polish CLI user experience with @clack/prompts for interactive flows, update-notifier for version awareness, and enhanced Commander.js help text with examples and colors. Generic patterns for any Node.js CLI.

CLI UX Polish

Goal

Improve the interactive experience with polished prompts, update notifications, and better help text.

1. Interactive Prompts with @clack/prompts

Install

pnpm add @clack/prompts

Confirmation Flow

import * as p from '@clack/prompts'

async function promptConfirmation(message: string): Promise<boolean> {
  const result = await p.confirm({ message })

  if (p.isCancel(result)) {
    p.cancel('Operation cancelled.')
    process.exit(130)
  }

  return result
}

Selection Flow

async function promptSelect<T extends string>(
  message: string,
  options: Array<{ value: T; label: string }>,
): Promise<T> {
  const result = await p.select({ message, options })

  if (p.isCancel(result)) {
    p.cancel('Operation cancelled.')
    process.exit(130)
  }

  return result as T
}

Spinner

const s = p.spinner()
s.start('Processing...')
await doWork()
s.stop('Done')

Important

• Only use @clack/prompts when process.stdout.isTTY is true (interactive terminal)
• In non-TTY / CI modes, skip prompts and auto-approve or fail with a clear message
• Always handle p.isCancel() — it returns a symbol when user presses Ctrl+C

2. Update Notifications

Install

pnpm add update-notifier

Usage

Add to the CLI entry point (before command parsing):

import updateNotifier from 'update-notifier'

const pkg = { name: 'your-package-name', version: currentVersion }
updateNotifier({ pkg }).notify()

This:

• Checks npm registry in the background (non-blocking)
• Caches the result for 24h
• Shows notification only when a new version exists
• Automatically respects NO_UPDATE_NOTIFIER=1 and CI environments

3. Enhanced Help Text

Add Examples to Commands

program
  .command('apply')
  .description('Apply changes')
  .addHelpText(
    'after',
    `
Examples:
  $ mycli apply --env staging
  $ mycli apply --env production --approve
  $ mycli apply --env dev --json`,
  )

Global Help Epilog

program.addHelpText(
  'after',
  `
Documentation: https://github.com/YOUR_ORG/YOUR_REPO
Report bugs:   https://github.com/YOUR_ORG/YOUR_REPO/issues`,
)

Colored Help (Optional)

import pc from 'picocolors'

program.configureHelp({
  formatHelp: (cmd, helper) => {
    const defaultHelp = helper.formatHelp(cmd, helper)
    if (process.stdout.isTTY) {
      return defaultHelp
        .replace(/^Usage:/m, pc.bold('Usage:'))
        .replace(/^Commands:/m, pc.bold('Commands:'))
        .replace(/^Options:/m, pc.bold('Options:'))
    }
    return defaultHelp
  },
})