cli-building

CLI の構築

最新のパターンとベストプラクティスに基づいて、コマンドラインインターフェイスを構築するためのガイドラインです。

使用する場面

• 新しい CLI ツールやコマンドを作成する
• 対話型のターミナルアプリケーションを構築する
• 既存のプロジェクトにコマンドを追加する
• コマンドラインインターフェイスを実装する
• CLI フレームワークを使用する

基本原則

• 非同期優先：すべての I/O 操作には async/await を使用し、ブロッキング操作は避けます
• 合成可能なコマンド：コマンドはモジュール化して再利用できるようにし、コマンド合成を使用します
• ストラテジーパターン：分岐するワークフローやタスクベースのコマンドには、ストラテジーパターンを使用します
• 出力の書式設定：Unicode 記号と色のサポートを適切に使用して書式を整えます

フレームワークの選択

TypeScript/JavaScript

stricli（@bloomberg/stricli、最新の非同期優先 CLI におすすめ）：

• 最初から async/await を前提に構築されています
• 完全な型推論に対応した型安全なコマンド定義
• 起動時のパフォーマンスを高める遅延読み込み
• 依存関係ゼロ

oclif（代替）：

• 豊富な機能を備えた成熟したフレームワーク
• プラグインシステム
• 複雑な CLI に適しています

Python

cyclopts（非同期優先の実装におすすめ）：

• 最新の非同期優先 CLI フレームワーク
• 優れた非同期サポートを備えた型安全な設計
• クリーンな API 設計

typer（完全な非同期サポートが利用可能な場合）：

• Python の型ヒントに基づいています
• クリーンで直感的です
• シンプルから中程度の複雑さの CLI に適しています

コマンドアーキテクチャ

合成可能なコマンド

コマンドは再利用可能なモジュールとして設計します：

• 共有コマンドユーティリティ
• コマンドミドルウェア
• 再利用可能なコマンドモジュール
• コマンド合成パターン

ストラテジーパターン

以下にはストラテジーパターンを使用します：

• ワークフローの分岐
• タスクベースのコマンド
• 動的なコマンドルーティング
• 条件付きのコマンド実行

出力の書式設定

• 絵文字は使用しない：明示的に指示されていない限り、絵文字は使用しません
• Unicode 記号：ステータス表示には Unicode 記号（✓、✗、→、⚠）を使用します
• 色のサポート：色ライブラリを使用し、ANSI コードをハードコードしないでください
• NO_COLOR：NO_COLOR 環境変数を常に尊重します
• 書式設定：読みやすさを高めるために書式設定（太字、薄字など）を使用します

非同期パターン

非同期優先の設計

すべての I/O は非同期にします：

• ファイル操作：非同期ファイル API を使用します
• ネットワークリクエスト：非同期 HTTP クライアントを使用します
• プロセス実行：非同期プロセス API を使用します
• データベース操作：非同期データベースクライアントを使用します

エラー処理

非同期エラーを適切に処理します：

• await とともに try/catch を使用します
• Promise の拒否を処理します
• 明確なエラーメッセージを表示します
• 適切な終了コードで終了します

コマンドの構造

基本的なコマンド

// stricli example
import { createCli } from '@bloomberg/stricli';

async function myCommand() {
  // Async implementation
}

const cli = createCli({
  name: 'my-cli',
  commands: {
    'my-command': myCommand
  }
});

cli.run();

# cyclopts example
from cyclopts import App

app = App()

@app.default
async def my_command():
    # Async implementation
    pass

if __name__ == '__main__':
    app()

ベストプラクティス

1. デフォルトで非同期：すべての操作を非同期にします
2. 合成可能な設計：再利用可能なコマンドモジュールを構築します
3. ストラテジーパターン：ワークフローの分岐に使用します
4. 適切な書式設定：NO_COLOR のサポートを備えた Unicode 記号と色を使用します
5. エラー処理：明確なエラーメッセージと終了コードを設定します
6. 型安全性：TypeScript の型または Python の型ヒントを使用します
7. テスト：コマンドを個別にテストします

参考資料

詳細なガイダンスについては、以下を参照してください：

• references/async-patterns.md - Async/await のベストプラクティス
• references/composable-commands.md - コマンド合成パターン
• references/strategy-pattern.md - ワークフロー向けストラテジーパターン
• references/output-formatting.md - 出力書式設定のガイドライン
• references/frameworks.md - フレームワークの比較と選択