gh-vanman2024-cli-builder-plugins-cli-builder/skills/commander-patterns/examples/basic-usage.md

Basic Commander.js Usage

Simple examples demonstrating core Commander.js features.

Example 1: Simple CLI with Commands

import { Command } from 'commander';

const program = new Command();

program
  .name('mycli')
  .description('My CLI tool')
  .version('1.0.0');

// Command without options
program
  .command('init')
  .description('Initialize project')
  .action(() => {
    console.log('Initializing project...');
  });

// Command with options
program
  .command('build')
  .description('Build project')
  .option('-w, --watch', 'watch mode')
  .action((options) => {
    console.log('Building...');
    if (options.watch) {
      console.log('Watch mode enabled');
    }
  });

program.parse();

Usage:

mycli init
mycli build
mycli build --watch
mycli --help
mycli --version

Example 2: Command with Arguments

import { Command } from 'commander';

const program = new Command();

program
  .name('mycli')
  .version('1.0.0');

program
  .command('greet <name>')
  .description('Greet someone')
  .action((name) => {
    console.log(`Hello, ${name}!`);
  });

program
  .command('add <a> <b>')
  .description('Add two numbers')
  .action((a, b) => {
    const sum = parseInt(a) + parseInt(b);
    console.log(`${a} + ${b} = ${sum}`);
  });

program.parse();

Usage:

mycli greet Alice
# Output: Hello, Alice!

mycli add 5 3
# Output: 5 + 3 = 8

Example 3: Options with Different Types

import { Command } from 'commander';

const program = new Command();

program
  .name('mycli')
  .version('1.0.0');

program
  .command('serve')
  .description('Start development server')
  // Boolean flag
  .option('-o, --open', 'open browser', false)
  // Option with value
  .option('-p, --port <port>', 'port number', '3000')
  // Option with default
  .option('-h, --host <host>', 'hostname', 'localhost')
  // Negatable option
  .option('--no-color', 'disable colors')
  .action((options) => {
    console.log(`Server running at http://${options.host}:${options.port}`);
    console.log('Open browser:', options.open);
    console.log('Colors:', options.color);
  });

program.parse();

Usage:

mycli serve
# Uses defaults

mycli serve --port 8080
# Uses custom port

mycli serve --open --no-color
# Opens browser and disables colors

Example 4: Global Options

import { Command } from 'commander';

const program = new Command();

program
  .name('mycli')
  .version('1.0.0')
  // Global options
  .option('-v, --verbose', 'verbose output')
  .option('-c, --config <path>', 'config file path');

program
  .command('deploy')
  .action((options, command) => {
    const globalOpts = command.parent?.opts();
    console.log('Deploying...');
    if (globalOpts?.verbose) {
      console.log('Verbose mode enabled');
      console.log('Config:', globalOpts.config);
    }
  });

program.parse();

Usage:

mycli deploy
# Normal output

mycli --verbose deploy
# Verbose output

mycli --verbose --config ./config.json deploy
# Verbose with custom config

Example 5: Multiple Commands

import { Command } from 'commander';
import chalk from 'chalk';

const program = new Command();

program.name('mycli').version('1.0.0');

program
  .command('init')
  .description('Initialize new project')
  .action(() => {
    console.log(chalk.green('✓ Project initialized'));
  });

program
  .command('build')
  .description('Build project')
  .action(() => {
    console.log(chalk.blue('Building...'));
    console.log(chalk.green('✓ Build complete'));
  });

program
  .command('test')
  .description('Run tests')
  .action(() => {
    console.log(chalk.blue('Running tests...'));
    console.log(chalk.green('✓ All tests passed'));
  });

program
  .command('deploy')
  .description('Deploy to production')
  .action(() => {
    console.log(chalk.yellow('Deploying...'));
    console.log(chalk.green('✓ Deployed'));
  });

program.parse();

Usage:

mycli init
mycli build
mycli test
mycli deploy
mycli --help  # Shows all commands

Running the Examples

Setup

1. Create a new project:

mkdir my-cli
cd my-cli
npm init -y

2. Install dependencies:

npm install commander chalk
npm install -D typescript @types/node tsx

3. Configure TypeScript:

npx tsc --init --target ES2022 --module ESNext

4. Create src/index.ts with any example above

5. Run with tsx:

npx tsx src/index.ts --help

Building for Production

# Build TypeScript
npx tsc

# Run compiled version
node dist/index.js

Making it Executable

Add to package.json:

{
  "bin": {
    "mycli": "./dist/index.js"
  }
}

Add shebang to top of source file:

#!/usr/bin/env node
import { Command } from 'commander';
// ... rest of code

Install globally for testing:

npm link
mycli --help