Build a CLI with Node.js: Commander vs yargs vs 2026

#!/usr/bin/env node
// src/cli.ts — Commander-based CLI
import { Command } from 'commander';
import { readFileSync } from 'fs';
import { resolve } from 'path';

const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));

const program = new Command();

program
  .name('mytool')
  .description('My awesome CLI tool')
  .version(pkg.version);

// Simple command with positional argument and options
program
  .command('hello <name>')
  .description('Say hello to someone')
  .option('-l, --loud', 'Loud mode (uppercase)')
  .option('-t, --times <number>', 'How many times', '1')
  .action((name: string, options: { loud: boolean; times: string }) => {
    const times = parseInt(options.times);
    const message = options.loud ? `HELLO, ${name.toUpperCase()}!` : `Hello, ${name}!`;
    for (let i = 0; i < times; i++) {
      console.log(message);
    }
  });

// Subcommand group — build and deploy under one namespace
const deploy = program.command('deploy').description('Deployment operations');

deploy
  .command('build')
  .description('Build the project for deployment')
  .option('--env <env>', 'Target environment', 'production')
  .option('--no-cache', 'Skip build cache')
  .action(async (options: { env: string; cache: boolean }) => {
    console.log(`Building for ${options.env}${options.cache ? '' : ' (no cache)'}...`);
    // Build logic here
  });

deploy
  .command('push <target>')
  .description('Push build artifacts to target')
  .option('--tag <tag>', 'Image tag to push', 'latest')
  .option('--dry-run', 'Print what would happen without executing')
  .action(async (target: string, options: { tag: string; dryRun: boolean }) => {
    if (options.dryRun) {
      console.log(`Would push tag ${options.tag} to ${target}`);
      return;
    }
    console.log(`Pushing ${options.tag} to ${target}...`);
  });

// Global error handler — cleaner output than default
program.configureOutput({
  writeErr: (str) => process.stderr.write(`Error: ${str}`),
  outputError: (str, write) => write(`\n${str}\n`),
});

// exitOverride makes Commander throw instead of calling process.exit
// This makes your CLI testable without process mocking
program.exitOverride();

program.parse();

#!/usr/bin/env node
import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

yargs(hideBin(process.argv))
  .scriptName('mytool')
  .usage('$0 <command> [options]')

  .command(
    'build',
    'Build the project',
    (yargs) =>
      yargs
        .option('env', {
          type: 'string',
          description: 'Target environment',
          choices: ['development', 'staging', 'production'] as const,
          default: 'production',
        })
        .option('no-cache', {
          type: 'boolean',
          default: false,
          description: 'Skip build cache',
        }),
    async (argv) => {
      console.log(`Building for ${argv.env}...`);
    }
  )

  .command(
    'deploy <target>',
    'Deploy to an environment',
    (yargs) =>
      yargs
        .positional('target', {
          describe: 'Deployment target',
          choices: ['staging', 'production'] as const,
        })
        .option('tag', {
          type: 'string',
          description: 'Docker image tag',
          default: 'latest',
        })
        .option('dry-run', {
          type: 'boolean',
          default: false,
        })
        // yargs .check() — custom validation with helpful error messages
        .check((argv) => {
          if (argv.target === 'production' && argv.tag === 'latest') {
            throw new Error('Deploying "latest" to production is not allowed — use a specific tag');
          }
          return true;
        }),
    async (argv) => {
      const { target, tag, dryRun } = argv;
      console.log(`Deploying ${tag} to ${target}${dryRun ? ' (dry run)' : ''}`);
    }
  )

  // Global middleware — runs before every command handler
  // Useful for: loading config, auth checks, telemetry
  .middleware(async (argv) => {
    if (process.env.CONFIG_PATH) {
      // Load config file and merge into argv
      const config = JSON.parse(await fs.readFile(process.env.CONFIG_PATH, 'utf8'));
      Object.assign(argv, config);
    }
    if (argv.verbose) {
      console.log('[verbose] Parsed args:', JSON.stringify(argv, null, 2));
    }
  })

  .option('verbose', {
    type: 'boolean',
    alias: 'v',
    global: true,
    description: 'Enable verbose logging',
  })
  .help()
  .strict()   // Error on unknown options
  .parse();

# Scaffold an oclif CLI project
npx oclif generate mycli
cd mycli

# Project structure:
# src/commands/           ← Each file = one command
# src/commands/build.ts   ← mytool build
# src/commands/deploy.ts  ← mytool deploy
# src/commands/deploy/    ← Subcommand directory
# src/hooks/              ← Lifecycle hooks (prerun, postrun, init)
# src/base-command.ts     ← Optional base class for shared behavior

// src/commands/build.ts — oclif command as a class
import { Command, Flags } from '@oclif/core';

export default class Build extends Command {
  static description = 'Build the project for deployment';

  static examples = [
    '<%= config.bin %> build',
    '<%= config.bin %> build --env staging --no-cache',
  ];

  static flags = {
    env: Flags.string({
      char: 'e',
      description: 'Target environment',
      options: ['development', 'staging', 'production'],
      default: 'production',
    }),
    'no-cache': Flags.boolean({
      description: 'Skip build cache',
      default: false,
    }),
  };

  async run() {
    const { flags } = await this.parse(Build);
    this.log(`Building for ${flags.env}...`);

    if (flags['no-cache']) {
      this.warn('Cache disabled — build will be slower');
    }

    // Build logic here
    this.log('Build complete');
  }
}

// src/commands/deploy.ts — oclif deploy command with args
import { Command, Flags, Args } from '@oclif/core';

export default class Deploy extends Command {
  static description = 'Deploy to an environment';

  static args = {
    target: Args.string({
      description: 'Deployment target',
      required: true,
      options: ['staging', 'production'],
    }),
  };

  static flags = {
    tag: Flags.string({
      char: 't',
      description: 'Docker image tag',
      default: 'latest',
    }),
    'dry-run': Flags.boolean({
      description: 'Simulate deployment without executing',
      default: false,
    }),
  };

  async run() {
    const { args, flags } = await this.parse(Deploy);

    if (args.target === 'production' && flags.tag === 'latest') {
      this.error('Cannot deploy "latest" to production — specify a tag with --tag', { exit: 1 });
    }

    this.log(`Deploying ${flags.tag} to ${args.target}...`);

    if (flags['dry-run']) {
      this.warn('Dry run — no changes will be made');
      return;
    }

    this.log('Deployment complete');
  }
}

{
  "name": "mycli",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "mycli": "./dist/cli.js"
  },
  "scripts": {
    "dev": "tsx src/cli.ts",
    "build": "esbuild src/cli.ts --bundle --platform=node --target=node20 --outfile=dist/cli.js --banner:js='#!/usr/bin/env node'",
    "prepublishOnly": "npm run build"
  },
  "dependencies": {
    "commander": "^12.0.0"
  },
  "devDependencies": {
    "esbuild": "^0.23.0",
    "tsx": "^4.0.0",
    "typescript": "^5.3.0",
    "@types/node": "^20.0.0"
  }
}

# Development: test locally before publishing
npm link          # Creates a global symlink to your current build
mycli --help      # Works from anywhere on your machine
npm unlink mycli  # Remove when done

# Publishing to npm
npm publish --access public            # Public package
npm publish --access restricted        # Private (requires paid account)
# For scoped packages: @yourname/mycli
# npm publish --access public for scoped

# Users install globally
npm install -g mycli
# or run without installing
npx mycli --help

# pkg — creates binaries for macOS, Linux, Windows
npm install -g pkg
pkg dist/cli.js --targets node20-macos-arm64,node20-linux-x64,node20-win-x64 --output dist/mycli

# Result:
# dist/mycli-macos-arm64  (~80MB — includes Node.js runtime)
# dist/mycli-linux-x64
# dist/mycli-win-x64.exe

yargs(hideBin(process.argv))
  // ... commands ...
  .completion('completion', 'Generate shell completion script')
  .parse();

mycli completion >> ~/.zshrc && source ~/.zshrc
# Now: mycli de<TAB> → mycli deploy

import omelette from 'omelette';

const completion = omelette('mycli <command>');
completion.on('command', ({ reply }) => {
  reply(['build', 'deploy', 'config']);
});
completion.init();

// test/cli.test.ts
import { describe, it, expect } from 'vitest';
import { program } from '../src/cli';

describe('CLI argument parsing', () => {
  it('rejects unknown options', () => {
    expect(() => program.parse(['node', 'mycli', '--unknown-flag'])).toThrow();
  });

  it('parses --times as integer', () => {
    let capturedOptions: { times: string } | undefined;
    program.command('hello <name>').action((name, options) => {
      capturedOptions = options;
    });
    program.parse(['node', 'mycli', 'hello', 'Alice', '--times', '3']);
    expect(capturedOptions?.times).toBe('3');
  });
});

function captureOutput(fn: () => void): { stdout: string; stderr: string } {
  const stdoutChunks: string[] = [];
  const stderrChunks: string[] = [];
  const originalStdout = process.stdout.write.bind(process.stdout);
  const originalStderr = process.stderr.write.bind(process.stderr);

  process.stdout.write = (chunk: string) => { stdoutChunks.push(chunk); return true; };
  process.stderr.write = (chunk: string) => { stderrChunks.push(chunk); return true; };

  try {
    fn();
  } finally {
    process.stdout.write = originalStdout;
    process.stderr.write = originalStderr;
  }

  return { stdout: stdoutChunks.join(''), stderr: stderrChunks.join('') };
}

import { execFileSync } from 'child_process';
import { resolve } from 'path';

const CLI_PATH = resolve(__dirname, '../dist/cli.js');

describe('CLI integration', () => {
  it('outputs help text when called with --help', () => {
    const result = execFileSync('node', [CLI_PATH, '--help'], {
      encoding: 'utf8',
      env: { ...process.env, NODE_ENV: 'test' },
    });
    expect(result).toContain('Usage:');
    expect(result).toContain('Commands:');
  });

  it('exits with code 1 on invalid arguments', () => {
    expect(() =>
      execFileSync('node', [CLI_PATH, '--invalid-flag'], { encoding: 'utf8' })
    ).toThrow(/Command failed/);
  });
});

import { input, password, select, confirm } from '@inquirer/prompts';

const projectName = await input({ message: 'Project name:' });
const dbPassword = await password({ message: 'Database password:' });

const environment = await select({
  message: 'Deploy to which environment?',
  choices: [
    { name: 'Staging', value: 'staging' },
    { name: 'Production', value: 'production', disabled: !hasProductionAccess },
  ],
});

const confirmed = await confirm({
  message: `Deploy ${projectName} to ${environment}?`,
  default: false,
});

if (!confirmed) {
  console.log('Deployment cancelled');
  process.exit(0);
}

import chalk from 'chalk';
import ora from 'ora';

// Semantic color usage — not decoration
console.log(chalk.green('✓'), 'Build completed');
console.log(chalk.yellow('⚠'), 'Using cached dependencies');
console.log(chalk.red('✗'), 'Deployment failed');

// Spinner for operations with unknown duration
const spinner = ora('Deploying to production...').start();
try {
  await deploy();
  spinner.succeed('Deployment complete');
} catch (err) {
  spinner.fail(`Deployment failed: ${err.message}`);
  process.exit(1);
}