CLIアプリ開発のための10個のポイント

CLI（コマンドラインインタフェース）はgitやnpm、dockerなど幅広く使われています。

CLIプログラムの強みは、シェルスクリプトを使用して一連作業のバッチ処理化を行なったり、ブラウザやデスクトップなど高度なソフトウェアを使用せずに実行できることにあります。

この記事では、CLIアプリを開発する際のポイントを紹介します。

1. stdout と stderrを正しく使い分ける

stdout（標準出力）とstderr（標準エラー出力）を正しく使い分けることは、スクリプト化して制御する際にとても有力です。

stdoutには進捗状況や処理結果の詳細情報の出力に使用しましょう。これらをログファイルにリダイレクトすることで、「正しく処理されたか？」という観点での調査が容易になります。

stderrにはエラーメッセージとエラー詳細情報の出力に使用しましょう。一般的に、ログを参照するのはエラーがあった時です。エラーログのみがまとまっているファイルがあれば、どんなエラーが発生していたのかすぐに分かるようになります。

2. ヘルプ出力を実装する

ヘルプはとても重要です。フラグ、サブコマンド、引数など、どのような組み合わせが持てるのかを確認するためのドキュメントです。

ヘルプは基本的には -h や --help フラグを使って呼び出すのが一般的です。

3. 出力を見やすく、便利にする

例えばファイルのダウンロードや巨大ファイルのコピーなど、長時間かかる処理の場合は、プログレスバーを表示するとユーザーは安心します。

またプログレスバーの表示が難しい場合はスピナーを活用することでも同じ効果を得ることができます。

ほとんどの環境で絵文字も使うことができます。警告⚠️など分かりやすく表示させることが出来るようになります。

4. エラー対処方法を表示する

ドキュメントを確認する目的の大半はエラーの対処法を得ることです。

エラー対処法はマニュアルに記載するだけでなく、標準エラー出力に表示することで対処までの時間を減らすことができます。

5. 理解しやすいフラグ名で実装する

一般的に使われているフラグを紹介します。どれも馴染みがあると思いますので、開発するCLIツールにこれらを実装すると操作性が向上すると思います。

• -a, --all : 全て、全体を表示するときに使います。psコマンドにありますね。
• -d, --debug : デバッグ情報を出力したいときに使用するフラグです。
• -f, --force : 強制的に処理を実行したときに使用するフラグです。rm -fなどで使ったことがある方もいるでしょう。
• --json : JSON形式で出力したいときに使用するフラグです。
• -h, --help : ヘルプを表示するときに使用します。
• -q, --quiet : 出力する内容を少なくする、もしくは出力しないときに使用します。スクリプトで実行するときにログ出力を少なくしたいときに使われます。
• --version : バージョン情報を表示するときに使用します。

⚠️ : -v は、verbose（詳細情報を表示する）とversion（バージョン情報を表示する）どちらの意味なのか混乱する可能性があります。そのため、-vは使用せず、--verbose , --version を使用することをお勧めします。

6. サブコマンドに動詞と名詞を使う

docker create というコマンドがありますが、これはdocker container create でも同じ動作をさせることができます。

docker container create は 「名詞」＋「動詞」の組み合わせですが、「動詞」＋名詞」の順番でも良いかもしれません。

docker create

docker create: The `docker container create` (or shorthand: `docker create`) command creates a new container from the specified image, without starting it. When...

docs.docker.com

7. ユーザー入力を受け入れる場合は検証して堅牢性を高める

ユーザーが作成したJSONやテキストファイルを入力して処理する場合は、正しいファイルになっているか検証を十分に行う必要があります。検証が不十分で処理が実行されることで、重大な不具合につながる可能性があります。

8. フラグやサブコマンドを廃止させずに将来性を高める

急にフラグやサブコマンドが廃止されると、ユーザーは戸惑いスクリプトは処理を停止してしまいます。インタフェースはできるだけ変更しないことが望ましいです。

ただしどうしてもインタフェースを変更しないといけない場合は、長い期間を与えて廃止までのプロセスを明確にした文書を用意してあげる必要があります。また、廃止予定のフラグや引数が与えられた場合は、警告を表示するようにしてください。

9. 覚えて貰えやすいプログラム名を検討する

CLIはGUIと違ってアイコンなどありませんので、覚えて貰えやすい名前をつける必要があります。

ポイントは以下の4つです。

• シンプルで記憶に残る名前：convertなど動詞を利用すると処理が想像できて記憶に残りやすいです。

• 大文字を使用しない、小文字のみ使用する：DownloadURLはどこを大文字にするか覚える必要がありますので、良いネーミングではありません。

• 短くする：psやcpやlsなど、短くて覚えやすいコマンドは多くあります。

• 入力しやすくする：QWERTYキーボードの配列を意識して、左右交互に入力できる単語を採用すると、入力しやすくなります。

10. アナリティクスを実装する

ユーザーがどのフラグをどのように使用しているか、使用状況やクラッシュデータを調査することは今後の改善に役立ちます。

ただし、これらのデータを収集する前に必ずユーザーの同意を得るようにしましょう。

同意を得ることができない場合は、ウェブドキュメントのページビュー数を計測したり、ユーザーとディスカッションすることで、統計データ以上の情報を得ることができるかもしれません。