kakudooo docs

CLIツールを作る時のargsとflagsの使い分け

以前、(heroku-review-apps-managerというgemを作った)でCLIツールを作った。会社で試しに使ってみてもらったところCLIに渡すパラメータはargumentsよりもflagsで指定できた方がよいのではないか？という意見をもらった。確かにとりあえずパラメータをargumentsとして指定する形にしていたので、argumentsとflagsのそれぞれの使い分けを調べて修正することにした。これは、その時調べたこと。

CLIにおけるargumentsとflags

clig.devというCLIの設計と実装におけるガイドラインが公開されており、argumentsとflagsのプラクティスについても詳しく書かれている。上記ガイドを参照しながら、それぞれのパラメータと使い分けをみていくことにする。

arguments(args)

コマンドにおいて順序のある(順番に意味のある)パラメータ

例: cpコマンドとそのarguments

cp foo bar

コマンドにおいて、複製元(foo)と複製先(bar)の順番にパラメータを指定することに意味がある。

flags

名前付きのパラメータで、-や--のprefixを伴うもの
順番に意味がない
ユーザーがパラメータを指定する場合もあれば、しない場合もある

例: -r,--recursive

argumentsとflagsの使い分け

まずflagsの使用を検討する。

Prefer flags to args.

arguments and flags

とあるように、flagsが好まれる。

何を指定するかが明確
パラメータの仕様変更に柔軟
- argumentsは後方互換性を持たせながら入力値のインターフェースを変更するのが難しい

前述したように、順番が強い意味を持つ場合はargumentsの使用を検討する。

自作CLIでの修正内容

上記を踏まえてheroku-review-apps-managerのパラメータを見直した。

before

heroku-review-apps-manager create-app BRANCH [PIPELINE_NAME] [REPOSITORY]

after

heroku-review-apps-manager create-app --branch BRANCH [--pipeline PIPELINE_NAME] [--repository REPOSITORY]

前述のプラクティスに則り、このコマンドに関してパラメータの順番に意味はないのでargumentsであったものを全てflagsにした。

実装

heroku-review-apps-managerでは、Thorを使っているので、以下のように実装できる。

desc "create-app", "Create review app"
option :branch, type: :string, aliases: :b, required: true
...
def create_app
...
end

create_appメソッドの引数がarguments
optionメソッドでの定義がflags

にそれぞれ対応する。

optionメソッドでは、aliasesキーで短縮形のflagsを定義することもできる。