cleye の使い方 — TypeScript対応の直感的CLI開発ツール

一言でいうと

cleyeは、Node.jsでコマンドラインツールを開発するための軽量パッケージです。argv解析、型安全なパラメータ/フラグ定義、ヘルプドキュメントの自動生成をミニマルなAPIで実現します。

どんな時に使う？

• Node.jsでCLIツールを自作したい時 — TypeScriptの型推論が効くため、フラグやパラメータの定義ミスをコンパイル時に検出できます
• サブコマンドを持つCLIを構築したい時 — git commitやnpm installのようなコマンド体系を簡単に定義できます
• --helpドキュメントを自動生成したい時 — フラグやパラメータの定義から、整形されたヘルプテキストが自動的に出力されます

インストール

# npm
npm i cleye

# yarn
yarn add cleye

# pnpm
pnpm add cleye

基本的な使い方

最もシンプルなパターンとして、引数とフラグを受け取るCLIスクリプトを作成してみます。

import { cli } from 'cleye'

const argv = cli({
  name: 'greet',

  // 位置パラメータの定義
  parameters: [
    '<first name>',   // 必須パラメータ
    '[last name]'     // オプショナルパラメータ
  ],

  // フラグ（オプション）の定義
  flags: {
    time: {
      type: String,
      description: 'Time of day to greet (morning or evening)',
      default: 'morning'
    }
  }
})

// パラメータへのアクセス（camelCaseに変換される）
const name = [argv._.firstName, argv._.lastName].filter(Boolean).join(' ')

// フラグへのアクセス
if (argv.flags.time === 'morning') {
  console.log(`Good morning ${name}!`)
} else {
  console.log(`Good evening ${name}!`)
}

$ node greet.js John Doe --time evening
Good evening John Doe!

$ node greet.js --help
greet

Usage:
  greet [flags...] <first name> [last name]

Flags:
  -h, --help                 Show help
      --time <string>        Time of day to greet (morning or evening) (default: "morning")

argv._.firstNameやargv.flags.timeにはTypeScriptの型推論が効くため、IDEの補完やコンパイル時チェックの恩恵を受けられます。

よく使うAPI

1. cli() — 基本のargv解析

cli()はcleyeのメインAPIです。設定オブジェクトを渡すと、解析済みのargvオブジェクトを返します。

import { cli } from 'cleye'

const argv = cli({
  name: 'my-tool',
  version: '1.0.0',
  parameters: ['<input file>'],
  flags: {
    output: {
      type: String,
      alias: 'o',
      description: 'Output file path',
    },
    verbose: {
      type: Boolean,
      alias: 'v',
      description: 'Enable verbose logging',
      default: false,
    }
  }
})

console.log(argv._.inputFile)   // string（必須なので常にstring）
console.log(argv.flags.output)  // string | undefined
console.log(argv.flags.verbose) // boolean

2. パラメータ定義 — 必須・オプショナル・スプレッド

パラメータは3種類の書式で定義できます。

const argv = cli({
  name: 'copy',
  parameters: [
    '<source>',            // 必須パラメータ
    '[destination]',       // オプショナルパラメータ
    '[extra files...]'     // スプレッドパラメータ（残り全部を配列で受け取る）
  ]
})

// $ copy src.txt dst.txt a.txt b.txt
argv._.source       // => "src.txt" (string)
argv._.destination  // => "dst.txt" (string | undefined)
argv._.extraFiles   // => ["a.txt", "b.txt"] (string[])

注意点: 必須パラメータはオプショナルパラメータより前に配置する必要があり、スプレッドパラメータは必ず最後に置きます。

3. command() — サブコマンドの定義

command()を使うと、git commitのようなサブコマンド体系を構築できます。

import { cli, command } from 'cleye'

const installCommand = command({
  name: 'install',
  description: 'Install packages',
  parameters: ['<package name>'],
  flags: {
    saveDev: {
      type: Boolean,
      alias: 'D',
      description: 'Save as devDependency',
      default: false,
    }
  }
})

const uninstallCommand = command({
  name: 'uninstall',
  description: 'Uninstall packages',
  parameters: ['<package name>'],
})

const argv = cli({
  name: 'my-pm',
  version: '1.0.0',
  commands: [
    installCommand,
    uninstallCommand,
  ]
})

// コマンドの判定
if (argv.command === 'install') {
  console.log(`Installing ${argv._.packageName}`)
  console.log(`devDependency: ${argv.flags.saveDev}`)
} else if (argv.command === 'uninstall') {
  console.log(`Uninstalling ${argv._.packageName}`)
}

$ my-pm install lodash -D
Installing lodash
devDependency: true

4. フラグの型とエイリアス

フラグにはString、Number、BooleanなどのJavaScriptコンストラクタを型として指定できます。配列型やカスタム型にも対応しています。

const argv = cli({
  name: 'build',
  flags: {
    // Boolean型（--minify で true）
    minify: {
      type: Boolean,
      alias: 'm',
      description: 'Minify output',
      default: false,
    },
    // Number型
    port: {
      type: Number,
      alias: 'p',
      description: 'Dev server port',
      default: 3000,
    },
    // 配列型（同じフラグを複数回指定可能）
    entry: {
      type: [String],
      alias: 'e',
      description: 'Entry points',
    },
  }
})

// $ build --minify -p 8080 -e src/a.ts -e src/b.ts
argv.flags.minify  // => true (boolean)
argv.flags.port    // => 8080 (number)
argv.flags.entry   // => ["src/a.ts", "src/b.ts"] (string[])

5. End-of-flags (--) の活用

--以降の引数を別途パースする機能です。npm run script -- argsのようなパターンを実装できます。

const argv = cli({
  name: 'runner',
  parameters: [
    '<script>',
    '--',
    '[arguments...]'
  ]
})

// $ runner echo -- hello world
argv._.script     // => "echo" (string)
argv._.arguments  // => ["hello", "world"] (string[])

--をparametersに含めない場合でも、argv._['--']から--以降の引数にアクセスできます。

類似パッケージとの比較

選定の目安:

• TypeScriptの型安全性を最優先 → cleye
• 大規模CLIで豊富なエコシステムが必要 → commander / yargs
• シンプルなスクリプトをサクッと作りたい → cleye / meow

注意点・Tips

フラグ名はcamelCaseで定義する

フラグ名をsaveDevのようにcamelCaseで定義すると、CLI上では--save-dev（kebab-case）として自動的に認識されます。コード内では常にcamelCaseでアクセスします。

// 定義: saveDev → CLI上: --save-dev
argv.flags.saveDev // ✅

unknownFlagsの扱い

定義していないフラグが渡された場合、argv.unknownFlagsに格納されます。厳密なバリデーションが必要な場合は、このプロパティをチェックしてエラーハンドリングを行いましょう。

--helpと--versionは自動追加

-h, --helpフラグは自動的に追加されます。versionプロパティを設定すると--versionフラグも自動で追加されます。手動で定義する必要はありません。

フラグのデリミタは複数対応

--flag value、--flag=value、--flag:value、--flag.valueの4種類のデリミタに対応しています。ユーザーの好みに合わせた入力を受け付けられます。

内部的にtype-flagを使用

フラグ解析はtype-flagパッケージに委譲されています。より高度なフラグ解析（カスタム型関数など）が必要な場合は、type-flagのドキュメントも参照してください。

まとめ

cleyeは「TypeScriptでCLIツールを型安全に作りたい」というニーズに最もフィットするパッケージです。宣言的な設定オブジェクトを1つ渡すだけで、パラメータ解析・フラグ解析・ヘルプ生成がすべて完了します。commanderやyargsほどの機能量は不要で、型推論の恩恵を最大限に受けたい場合に最適な選択肢です。