Node.js CLI 引数パーサーの深掘り比較：argparse vs commander vs minimist vs yargs

Node.js で CLI ツールを作る際、ユーザーからの入力を安全かつ柔軟に処理するための引数パーサーは欠かせません。argparse、commander、minimist、yargs はそれぞれ異なる哲学でこの課題に取り組んでおり、用途に応じて適切な選択が重要です。以下では、実際のコード例を交えながら、各ライブラリの特徴と使いどころを詳しく見ていきます。

🧩 基本的な引数解析：シンプルなフラグと値

まずは最も基本的なケース — -f file.txt や --verbose のようなフラグを処理する方法を比較します。

minimist は最小限の処理に特化しており、単純なオブジェクトを返します。

// minimist
const minimist = require('minimist');
const args = minimist(process.argv.slice(2));
// 入力: node app.js -f file.txt --verbose
// 出力: { _: [], f: 'file.txt', verbose: true }

commander はメソッドチェーンでオプションを宣言します。

// commander
const { Command } = require('commander');
const program = new Command();
program
  .option('-f, --file <path>', 'input file path')
  .option('-v, --verbose', 'enable verbose mode');
program.parse();
const options = program.opts();
// options.file と options.verbose が利用可能

yargs は .option() で設定し、.argv で結果を取得します。

// yargs
const yargs = require('yargs');
const argv = yargs
  .option('f', {
    alias: 'file',
    type: 'string',
    description: 'input file path'
  })
  .option('verbose', {
    type: 'boolean',
    description: 'enable verbose mode'
  })
  .argv;
// argv.file と argv.verbose が利用可能

argparse は Python 風の明示的なパーサー定義を使います。

// argparse
const { ArgumentParser } = require('argparse');
const parser = new ArgumentParser({
  description: 'Process some files.'
});
parser.addArgument(['-f', '--file'], {
  help: 'input file path',
  required: true
});
parser.addArgument(['--verbose'], {
  action: 'storeTrue',
  help: 'enable verbose mode'
});
const args = parser.parseArgs();
// args.file と args.verbose が利用可能

📚 サブコマンドのサポート：階層的な CLI 構造

Git や Docker のように、git commit や docker run のようなサブコマンドを持つ CLI を作る場合の違いを見ます。

minimist にはサブコマンドの概念がありません。自前で _ 配列を解析する必要があります。

// minimist（サブコマンドなし）
const args = minimist(process.argv.slice(2));
// 入力: node app.js commit -m "msg"
// args._ → ['commit']
// 以降の処理はすべて手動

commander は .command() でサブコマンドを自然に定義できます。

// commander
const { Command } = require('commander');
const program = new Command();

program
  .command('commit')
  .option('-m, --message <msg>', 'commit message')
  .action((options) => {
    console.log('Committing with:', options.message);
  });

program.parse();

yargs は .command() で同様の機能を提供し、さらに非同期アクションもサポートします。

// yargs
const yargs = require('yargs');
yargs
  .command('commit', 'make a commit', (yargs) => {
    yargs.option('m', {
      alias: 'message',
      type: 'string',
      demandOption: true
    });
  }, (argv) => {
    console.log('Committing with:', argv.message);
  })
  .parse();

argparse は addSubparsers() を使ってサブコマンドを実現できますが、API がやや冗長です。

// argparse
const { ArgumentParser } = require('argparse');
const parser = new ArgumentParser();
const subparsers = parser.addSubparsers({ dest: 'command' });

const commitParser = subparsers.addParser('commit');
commitParser.addArgument(['-m', '--message'], {
  help: 'commit message',
  required: true
});

const args = parser.parseArgs();
if (args.command === 'commit') {
  console.log('Committing with:', args.message);
}

🆘 ヘルプとバリデーション：ユーザー体験の差

エンドユーザーが迷わないようにするためのヘルプメッセージと、入力値の検証機能の違いです。

minimist はヘルプ生成もバリデーションも提供しません。すべて自前実装が必要です。

commander は .help() で自動生成されるヘルプを提供し、.requiredOption() で必須チェックが可能です。

// commander
program
  .requiredOption('-f, --file <path>', 'must specify input file')
  .parse();
// 不正な入力時は自動でエラー表示＋ヘルプ出力

yargs は最も洗練されたヘルプを提供し、.demandOption() や .choices()、.coerce() などで詳細なバリデーションが可能です。

// yargs
yargs
  .option('format', {
    choices: ['json', 'yaml'],
    default: 'json'
  })
  .demandOption('file')
  .argv;
// 無効な format 値を指定すると自動でエラー

argparse は required や choices オプションで厳密なバリデーションができ、ヘルプも自動生成されます。

// argparse
parser.addArgument(['--format'], {
  choices: ['json', 'yaml'],
  defaultValue: 'json'
});
// 無効な値は自動で拒否され、ヘルプ表示

⚙️ 設定とカスタマイズ性

minimist は設定オプションが非常に少なく、ほぼ「そのまま」の挙動しかできません。

commander は .configureHelp() や .configureOutput() で出力のカスタマイズが可能です。

yargs は .usage()、.epilogue()、.locale() など多数のメソッドでヘルプの見た目や言語を細かく調整できます。

argparse は formatterClass や prefixChars など、Python の argparse 由来の高度なカスタマイズが可能です。

📌 まとめ：どのライブラリを選ぶべきか

💡 最終的なアドバイス

• 内部スクリプトやビルドツールの補助コマンド → minimist
• 開発者向け CLI ツール（例：フレームワークの CLI） → commander
• 一般ユーザー向けアプリケーション（例：データ変換ツール） → yargs
• 科学計算やデータ処理系 CLI で厳密な入力制御が必要 → argparse

どのライブラリも安定しており、新規プロジェクトでの使用に問題はありません。あなたの CLI が「誰のために」「何を目的に」作られるかを軸に、最適な選択をしてください。