@d-zero/roar
v2.3.1
Published
A CLI helper library with per-subcommand flag support
Readme
@d-zero/roar
サブコマンドごとに型付きフラグを定義できる CLI ヘルパー(yargs-parserベース)。
Installation
yarn add @d-zero/roarUsage
import { parseCli } from '@d-zero/roar';
const result = parseCli({
name: 'my-tool',
version: pkg.version,
globalFlags: {
config: { type: 'string', shortFlag: 'c', desc: 'Config file' },
},
commands: {
crawl: {
desc: 'Crawl a website',
usage: ['<URL> [options]', '<archive> --append <URL> [options]'],
flags: {
depth: { type: 'number', shortFlag: 'd', desc: 'Max depth', default: 10 },
append: {
type: 'string',
shortFlag: 'A',
desc: 'Append crawl',
valueName: 'URL',
group: 'Crawl modes',
},
verbose: { type: 'boolean', shortFlag: 'v', desc: 'Verbose output' },
},
},
analyze: { desc: 'Run analysis' },
},
onError: () => true,
});
result.flags.config; // string | undefined(全コマンド共通なので絞り込み不要)
if (result.command === 'crawl') {
result.flags.depth; // number(default から推論)
result.flags.verbose; // boolean | undefined
}位置引数とフラグは任意の順序で混在可能。--以降はすべて位置引数として扱う。
globalFlags— 全コマンド共通のフラグ。各コマンドのflagsとあわせて解析・型付けされる。コマンド名より後ろに置く(my-tool crawl --config x)。コマンド側のフラグとコマンドライン上の名前(kebab-case の長い名前・shortFlag)が衝突するとparseCliが例外を投げるisMultipleでないフラグを繰り返し指定した場合は最後の値を採用するisRequiredのフラグを省略すると、エラーを stderr に出力してexit(1)する
Help 表示
--help/-hは stdout に整形済みヘルプを出力してexit(0)する。トップレベルではコマンド一覧、コマンドの後ろではそのコマンドのフラグ一覧を表示する。
usage(string | string[])—Usage:行の自由記述。複数指定で相互排他の起動モードを 1 行ずつ列挙できる。プログラム名とコマンド名は自動で前置されるvalueName— string/number フラグの値プレースホルダ(--interval <ms>のような表記)。省略時は<value>/<n>group— フラグをセクション見出しの下にまとめる。未指定のフラグはOptions:直下(globalFlagsはGlobal options:直下で、トップレベルと全コマンドの help に表示される)subCommands— help 専用のサブサブコマンドメタデータ(パースには影響しない)。コマンドの help にサブコマンド一覧を表示し、my-tool query <file> pages --helpのようにサブコマンド名を含めるとそのサブコマンドに適用されるフラグだけに絞った help を表示する。各エントリのflagsに適用フラグのキーを列挙し、どのエントリからも参照されないフラグは全サブコマンド共通として常に表示される
説明文は端末幅(上限 100 桁)で折り返され、ラベル列の幅はフラグ長に応じて自動調整される。
--version/-vの発火位置(argv[0]限定)、空文字列versionの扱い、フラグ型推論の挙動はsrc/parse-cli.tsの JSDoc を参照。
