cli-builder

CLI Builder Skill

Core Workflows

Workflow 1: Primary Action

1. Analyze the input and context
2. Validate prerequisites are met
3. Execute the core operation
4. Verify the output meets expectations
5. Report results

Overview

This skill helps you build professional command-line interfaces with excellent user experience. Covers argument parsing, interactive prompts, progress indicators, colored output, and cross-platform compatibility.

CLI Design Philosophy

Principles of Good CLI Design

1. Predictable: Follow conventions users expect
2. Helpful: Provide clear help text and error messages
3. Composable: Work well with pipes and other tools
4. Forgiving: Accept common variations in input

Design Guidelines

• DO: Use conventional flag names (-v, --verbose, -h, --help)
• DO: Provide meaningful exit codes
• DO: Support --version and --help on all commands
• DO: Use colors meaningfully (errors=red, success=green)
• DON'T: Require interactive input when running in pipes
• DON'T: Print to stdout when outputting errors
• DON'T: Ignore signals (Ctrl+C should exit cleanly)

Node.js CLI Development

Project Setup

# Initialize CLI project
mkdir my-cli && cd my-cli
npm init -y

# Install core dependencies
npm install commander chalk ora inquirer

# Optional: TypeScript support
npm install -D typescript @types/node @types/inquirer ts-node

Package.json Configuration

{
  "name": "my-cli",
  "version": "1.0.0",
  "description": "A powerful CLI tool",
  "bin": {
    "mycli": "./bin/cli.js"
  },
  "files": [
    "bin",
    "dist"
  ],
  "scripts": {
    "build": "tsc",
    "dev": "ts-node src/cli.ts",
    "link": "npm link"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

Commander.js - Command Structure

// src/cli.ts
import { Command } from 'commander';
import { version } from '../package.json';

const program = new Command();

program
  .name('mycli')
  .description('A powerful CLI for doing awesome things')
  .version(version, '-v, --version', 'Display version number');

// Simple command
program
  .command('init')
  .description('Initialize a new project')
  .argument('[name]', 'Project name', 'my-project')
  .option('-t, --template <type>', 'Template to use', 'default')
  .option('--no-git', 'Skip git initialization')
  .option('-f, --force', 'Overwrite existing files')
  .action(async (name, options) => {
    console.log(`Creating project: ${name}`);
    console.log(`Template: ${options.template}`);
    console.log(`Git: ${options.git}`);
  });

// Command with subcommands
const config = program
  .command('config')
  .description('Manage configuration');

config
  .command('get <key>')
  .description('Get a configuration value')
  .action((key) => {
    console.log(`Getting config: ${key}`);
  });

config
  .command('set <key> <value>')
  .description('Set a configuration value')
  .action((key, value) => {
    console.log(`Setting ${key} = ${value}`);
  });

config
  .command('list')
  .description('List all configuration')
  .option('--json', 'Output as JSON')
  .action((options) => {
    if (options.json) {
      console.log(JSON.stringify({ key: 'value' }, null, 2));
    } else {
      console.log('key = value');
    }
  });

// Parse arguments
program.parse();