前回の記事では、 , we explored how to build a CLI tool from the ground up. Now, let's take the next step — how do you make it good? Ultimately, the key lies in ease of use. A well-designed CLI feels intuitive, predictable, and efficient for the user. However, this ease of use is achieved through several distinct design principles, which we'll explore in this article. 結局のところ、鍵は使いやすさにあります。 コマンドラインの芸術をマスターする:強力なツールを開発する究極のガイド コマンドラインの芸術をマスターする:強力なツールを開発する究極のガイド デモ用に、私たちは使用します。 , しかし、原則は、あなたが使用する可能性のあるほぼすべての CLI フレームワークに適用されます。 Python図書館をクリック パラメータ ほとんどの CLI ツールはユーザーからの入力を受け入れています。この入力はほとんどの場合インタラクティブではありません。 ツールがどのように動くかを定義します。 parameters 例えば、The コマンドには少なくとも2つのパラメータが必要です。 cp 
 
 
 コピーするファイルまたはディレクトリへのパス、および 目的地への道。 また、オプションのパラメータを採用することもできます。 verbose output を可能にします。 -v 一般的には、2種類のパラメータがあります。 そして ほとんどの CLI ライブラリでは、必要なパラメータが (or positional arguments), and optional parameters are called . required optional arguments options ポジティブな議論 名前の通り、 ユーザーは特定の順序で値を提供し、ツールはそれに応じてそれらを解釈します。 positional arguments 例えば、もし、The コマンドは2つのポジション論点を期待します。 そして ユーザはこれを以下のように呼ぶでしょう。 cp 源泉 目的地 cp source destination
 あなたのツールが入力を必要とする場合でも、ユーザーがすべての値を手動で指定することはしばしば困難(そして不要)です。 . if you can provide a sensible default, make it an option instead of an argument 例えば、A パラメータは default to ユーザーが位置を覚え、常に情報を伝えることを強制することは、価値を追加するものではなく、摩擦を加えるだけです。 --log-level info 複数の議論 時には、ツールが受け入れる必要があるかもしれません。 一般的な例は、複数のソース ファイルを 1 つのターゲット ディレクトリにコピーするように指定することです. This allows the user to run one command instead of several: multiple values cp source1 source2 destination
 いくつかのカテゴリーがありますが、典型的には、 複数の値を受け入れることができます. あなたのコード(アルバムパッサーではなく)は、追加の検証と論理を処理する必要があります。 only one argument オプション ユーザーがパラメータを名前で指定することを許可し、しばしば形式で ユーザがオプションを提供しない場合、ツールはそのデフォルト値を使用します。 Options --option value 例えば: --log-level debug
 特別な種類のオプションは、旗 — 価値をとることはありません. The mere presence of the flag shifts a behavior, such as enabling verbose output: 旗の単なる存在は、言葉のない出力を可能にするような行動を変えます。 --verbose
 オプション名は ユーザーが目的を簡単に理解できるようになります。 clear and descriptive 実施例: @click.command()
@click.option('--verbose', is_flag=True)
@click.option('--log-level', default="info")
@click.argument('srcs', nargs=-1)
@click.argument('dst')
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 現在、ツールはいくつかの方法で呼び出すことができます: cp --verbose --log-level trace source1 source2 destination
cp source destination
 ショートオプション これまで、長いオプション名を使用してきました これらはスクリプトのための理想的です、彼らは自己説明し、一瞬で理解しやすいです。 しかし、迅速で一度のコマンドの場合、ユーザーはしばしば まるで 代わりに 短いフォームを導入するときに選択してください. すべてのオプションに1つのオプションが必要ではありません. あなたのツールに多くのオプションがある場合は、直感的な文字がすぐになくなります - 特に複数のオプションが同じオプションから始まる可能性があります。 . short options -v --verbose frequently used options 例: @click.command()
@click.option('-v', '--verbose', is_flag=True)
@click.option('--log-level', default="info")
@click.argument('srcs', nargs=-1)
@click.argument('dst')
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 現在、両方の形態が働いている: cp -v source destination
cp --verbose source destination
 ユーザー入力の検証と迅速な失敗 強力なCLIツールは、 明確で操作可能なメッセージで失敗します. ほとんどの CLI フレームワークはこのパターンをサポートします。 validate user input early たとえば、Click では、有効なログ レベルとパス アルゴリズムを自動的に実行できます。 @click.command()
@click.option('-v', '--verbose', is_flag=True)
@click.option('--log-level', default="info", type=click.Choice(["debug", "info", "error"]))
@click.argument('srcs', nargs=-1, type=click.Path())
@click.argument('dst', type=click.Path())
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 しかし、あなたはまだ必要かもしれません。 わたしたちのうち 例: custom logic copy 
 
 
 ソースが 1 つある場合、ターゲットはファイルまたはディレクトリかもしれません。 複数のソースがある場合、目的地はディレクトリでなければなりません - でなければ、ファイルは予期せず互いに書き換えられます。 一般的な CLI ライブラリは、そのようなケースを自動的に処理しませんので、この検証はあなたのコードに存在する必要があります。 メッセージ サポート 良いツールは常に良いツールを提供します。 . help message ユーザーは、こういうものを実行できるはずです。 見る : --help 
 
 
 
 どのパラメータが利用可能か 彼らの意味 受け入れられたタイプまたは値(例えば、有効なログレベル) 明確なヘルプメッセージは、時間を節約し、エラーを削減し、ツールに対するユーザーの信頼を向上させます。 あなたの生態系パターンに従って 最後に、偉大なCLIツールが感じる。 あなたの環境の他のツールを研究し、彼らの慣習に従う - 特に . native naming options and arguments 例えば、Unixの世界では、 で、 そして、 すべて使用 そして 立場的な論点として、 常に先行 . cp mv rsync source destination source destination オプション名とオプション文字(英語版) ボリュームで、 回復するため、 乾燥するために、 助けを求めて)あなたのツールをユーザーのワークフローにシームレスに組み込む。 -v -r -n -h/--help あなたのツールが生態系の自然な部分のように感じるとき、ユーザーはそれを採用する可能性が高くなり、それを楽しむでしょう。 他の側面 Beyond parameters and arguments, there are several other factors that distinguish a  これらの側面は、ツールがスクリプトとどのように統合されるか、ユーザーが問題をデバッグする方法、およびより大きなワークフローにどれほど容易に適合するかに影響します。 good 出口コード すべてのプログラムが返ってくる このコードは、プログラムが成功したか失敗したかを呼び出す者に知らせます。 exit code 条約により: 
 
 
 0 成功の意味 ゼロ以外の値はエラーを示します。 出力コードのための普遍的な基準はありませんが、少なくとも . exit with a non-zero code on any error よりよい一貫性のために、従うべき条約を考慮して、 これらは、Unixの世界で広く認識されています。 Advanced Bash-Scripting ガイド あなたはまた、 彼らを含め、The ユーザや自動化システムが出口コード3の意味を理解すると、エラーをより賢く処理できます(例えば、リトリ、ジャンプ、警告など)。 document your exit codes --help STDOUT VS STDERR よく動作する CLI ツールは、2 つの標準出力ストリームを区別します: 
 
 
 STDOUT — for regular, expected output. 通常の、予想される出力 STDERR - エラー、警告、または診断メッセージ この分離により、ユーザーとスクリプトはそれぞれのストリームを独立して処理することができます. たとえば、ユーザーは、コンソール上にエラーメッセージが表示されながら、通常の出力をファイルにリダイレクトできます。 mytool > output.txt
 エラーを削除する: mytool 2>/dev/null
 あなたのツールがデータとエラーをSTDOUTに書き込む場合、ユーザーは出力を手動でフィルタリングする必要があります。 特に、あなたのツールの出力が他のプログラムによって消費される場合、STDOUTをクリーンで予測可能に保つことは不可欠です。 出力形式 あなたのツールが他のツールやスクリプトによって消費される可能性のあるデータを生成する場合は、サポートするのが賢明です。 JSONやYAMLなどのフォーマット machine-readable output 例えば: mytool --output json
 これは自動化をより容易にします - 他のツールは、スペース、並列、または点差の変更時に壊れる脆弱な文字列の解析に依存する代わりに、標準の解析器を使用することができます。 しかし、人間の読み取り能力を犠牲にしないでください. 多くのユーザーはまだあなたのツールをインタラクティブに実行します. 最良のアプローチは: 
 
 
 Default to human-readable output (nicely formatted text) 構造化された出力のための旗を提供する(例えば --json または --format で、複数の形式をサポートしたい場合) いくつかのCLIツールも提供します。 , 端末に書き込むときに、かなりプリントされたテキストを送信するが、別のプロセスにパイプされたときにJSON - は、 または 振る舞い auto-detection kubectl gh ミスメッセージ 良いエラーメッセージは以下の通りです。 
 
 
 
 Clear - state what went wrong. 何が間違ったかを明確にする Actionable - suggest how to fix it. 行動可能 - suggest how to fix it. 一貫性 - 全体に同じトーンと構造を使用する 悪い例: Error: failed
 より良い例: Error: Could not open file '/tmp/input.txt' — file not found.
Hint: Verify that the path is correct and you have read permissions.
 良いエラー処理は、ユーザーの時間を節約し、ツールへの信頼を構築するのに役立ちます。 「Logging and Verbosity」 ユーザーは、どのくらいの情報が見られるかをコントロールすることを好みます 典型的なアプローチ: 
 
 
 
 最小出力のための静けさ --verbose for detailed messages 詳細なメッセージ --debug for developer-level tracing (デベロッパーレベルのトラッキング) ユーザーがその文脈に適した正しい量の情報を選択できるようにログレベルを設計します。 適切な出力コードと組み合わせると、これらのレベルはデバッグと自動化をよりスムーズにします。 応答性とパフォーマンス あなたの CLI が重い操作を行う場合は、提供することを検討してください。 または 例えば: progress indicators spinners Downloading files... 45% complete
 同時に、ツールが非インタラクティブモード(例えば、スクリプトの一部として)で実行されているときに不要なアニメーションや出力を避ける必要があります。 結論 CLI ツールの構築は比較的簡単です。 良いコマンドラインツールは自然に感じ、予測可能に振る舞い、静かにユーザーのワークフローに消える。 既存のユーザーの働き方に適応します。 good IT この記事を通して、私たちはその経験に貢献するものを見てきました: 
 
 
 
 
 
 
 シンプルさと柔軟性のバランスをとる明確で一貫したパラメータ Meaningful   that communicate success or failure exit codes STDOUTとSTDERRの適切な使用により、データを診断から分離する 人間と機械の両方で読み取り可能で構造化された出力フォーマット 有用なエラーメッセージと予測可能な行動 あなたのエコシステムの規則に従い、最初からあなたのツールが馴染みを感じるように 結局のところ、最高のCLIツールは共通の特徴を共有している:彼らは 彼らはすぐに始まり、すぐに失敗し、自分自身を明確に説明し、より大きなシステムやスクリプトにシームレスに統合します。 respect the user’s time あなたがこれらの原則を念頭に留めている場合 - あなたのユーザーのための明確さ、一貫性、および共感 - あなたのCLIツールは、 利用するのが楽しみです。 仕事

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Read My Stories

このオーディオは、ストーリーの元の言語で制作されています。

開発者が実際に使用することを愛するCLIツールを設計する方法

About Author

コメント

ラベル

この記事は

Related Stories

ユニークなエコシステムを支えるビットコインUTXOのモデル

Claude Sonnet 3.5 システムプロンプトの漏洩: 法医学的分析

暗号通貨の成長: 効果的なユーザーペルソナの作成

タップして稼ぐ：テレグラムはソラナより先に次の100億人の暗号通貨ユーザーを獲得する可能性がある

ユニークなエコシステムを支えるビットコインUTXOのモデル

Claude Sonnet 3.5 システムプロンプトの漏洩: 法医学的分析

暗号通貨の成長: 効果的なユーザーペルソナの作成

タップして稼ぐ：テレグラムはソラナより先に次の100億人の暗号通貨ユーザーを獲得する可能性がある

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps