building-clis

CLI の構築

最新のフレームワークを使用して、堅牢な引数解析、設定管理、シェル連携を備えたプロフェッショナルなコマンドラインインターフェースを、Python、Go、Rust で構築します。

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• 開発者向けツールや自動化用 CLI を構築する
• インフラ管理ツール（デプロイ、モニタリング）を作成する
• API クライアントのコマンドラインツールを実装する
• 既存のプロジェクトに CLI 機能を追加する
• ユーティリティを配布用にパッケージ化する（PyPI、Homebrew、バイナリリリース）

よくあるきっかけ：「CLI ツールを作成する」「コマンドラインインターフェースを構築する」「CLI 引数を追加する」「コマンドラインオプションを解析する」「シェル補完を生成する」

フレームワークの選択

選択の簡易ガイド

Python プロジェクト：

• Typer（推奨）：ボイラープレートを最小限に抑え、型安全な最新の CLI を構築できます
• Click：複雑なコマンド階層に対応する、成熟した柔軟な CLI を構築できます

Go プロジェクト：

• Cobra（推奨）：エンタープライズツール（Kubernetes、Docker、GitHub CLI）で業界標準です
• urfave/cli：シンプルな CLI 向けの軽量な代替手段です

Rust プロジェクト：

• clap v4（推奨）：型安全で、derive API または実行時の柔軟性に優れた builder API を利用できます

フレームワークの詳細な比較と選択基準については、references/framework-selection.md を参照してください。

基本パターン

引数とオプションとフラグ

位置引数：

• 位置によって識別される主要な入力です
• 必須入力に使用します（引数は最大 2～3 個）
• 例：convert input.jpg output.png

オプション：

• 値を伴う名前付きパラメーターです
• 設定や任意の入力に使用します
• 例：--output file.txt、--config app.yaml

フラグ：

• ブール値のオプションです（指定すると true になります）
• スイッチや切り替えに使用します
• 例：--verbose、--dry-run、--force

判断表：

用途	種類	例
主要な必須入力	位置引数	git commit -m "message"
任意の設定	オプション	--config app.yaml
ブール値の設定	フラグ	--verbose、--force
複数の値	可変長引数	files...

包括的な解析パターンについては、references/argument-patterns.md を参照してください。

サブコマンドの構成

フラット構造（1 レベル）：

app command1 [args]
app command2 [args]

用途：操作が 5～10 個ある小規模な CLI

グループ化構造（2 レベル）：

app group subcommand [args]

用途：論理的なグループ分けがある中規模の CLI（コマンド数 10～30 個） 例：kubectl get pods、kubectl create deployment

入れ子構造（3 レベル以上）：

app group subgroup command [args]

用途：階層が深い大規模な CLI（コマンド数 30 個以上） 例：gcloud compute instances create

構成の方法については、references/subcommand-design.md を参照してください。

設定管理

標準の優先順位（高い順）：

1. CLI 引数／フラグ（ユーザーによる明示的な入力）
2. 環境変数（セッションでの上書き）
3. 設定ファイル - ローカル（./config.yaml）
4. 設定ファイル - ユーザー（~/.config/app/config.yaml）
5. 設定ファイル - システム（/etc/app/config.yaml）
6. 組み込みのデフォルト値（ハードコードされた値）

ベストプラクティス：

• --help に優先順位を記載します
• 実行前に設定ファイルを検証します
• 有効な設定を表示する --print-config を用意します
• 設定ファイルには XDG Base Directory（~/.config/app/）を使用します

各言語での実装パターンについては、references/configuration-management.md を参照してください。

出力形式

形式の選択：

用途	形式	タイミング
人が読む場合	色付きテキスト、テーブル	対話モードのデフォルト
機械が処理する場合	JSON、YAML	--output json、パイプ処理
ログ記録／デバッグ	プレーンテキスト	--verbose、stderr
進捗の追跡	プログレスバー、スピナー	時間のかかる操作

ベストプラクティス：

• デフォルトでは、人が読みやすい出力にします
• --output フラグ（json、yaml、table）を用意します
• ログには stderr、データには stdout を使用します
• TTY を自動検出します（対話的でない場合は色を無効にします）
• 終了コードを使用します：0 = 成功、1 = エラー、2 = 使用方法のエラー

形式の戦略については、references/output-formatting.md を参照してください。

言語別クイックスタート

Typer を使った Python

インストール：

pip install "typer[all]"  # Includes rich for colored output

基本例：

import typer
from typing import Annotated

app = typer.Typer()

@app.command()
def greet(
    name: Annotated[str, typer.Argument(help="Name to greet")],
    formal: Annotated[bool, typer.Option(help="Use formal greeting")] = False
):
    """Greet someone with a message."""
    greeting = "Good day" if formal else "Hello"
    typer.echo(f"{greeting}, {name}!")

if __name__ == "__main__":
    app()

主な機能：

• 型ヒントによる自動検証
• デコレーターによる最小限の定型コード
• ヘルプテキストの自動生成
• 色付き出力のための Rich との統合

サブコマンド、設定管理、対話型機能を含む、完全に動作する例については、examples/python/ を参照してください。

Cobra を使った Go

インストール：

go get -u github.com/spf13/cobra@latest

基本例：

var rootCmd = &cobra.Command{
    Use:   "greet [name]",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Hello, %s!\n", args[0])
    },
}

rootCmd.Flags().Bool("formal", false, "Use formal greeting")
rootCmd.Execute()

主な機能：

• POSIX 準拠のフラグ
• 設定のための Viper 統合
• サブコマンドアーキテクチャ
• シェル補完の生成

Viper の設定や複数階層のサブコマンドを含む、完全に動作する例については、examples/go/ を参照してください。

clap を使った Rust

インストール（Cargo.toml）：

[dependencies]
clap = { version = "4.5", features = ["derive"] }

基本例（Derive API）：

use clap::Parser;

#[derive(Parser)]
#[command(about = "Greet someone")]
struct Cli {
    /// Name to greet
    name: String,

    /// Use formal greeting
    #[arg(long)]
    formal: bool,
}

fn main() {
    let cli = Cli::parse();
    let greeting = if cli.formal { "Good day" } else { "Hello" };
    println!("{}, {}!", greeting, cli.name);
}

主な機能：

• コンパイル時の型安全性
• Derive API（宣言型）または Builder API（プログラム型）
• 包括的な検証
• パフォーマンスを最適化

サブコマンドや Builder API のパターンを含む、完全に動作する例については、examples/rust/ を参照してください。

対話型機能

進捗インジケーター

Python（rich）：

from rich.progress import track
for _ in track(range(100), description="Processing..."):
    time.sleep(0.01)

Go（progressbar）：

import "github.com/schollz/progressbar/v3"
bar := progressbar.Default(100)
for i := 0; i < 100; i++ {
    bar.Add(1)
}

Rust（indicatif）：

use indicatif::ProgressBar;
let bar = ProgressBar::new(100);
for _ in 0..100 {
    bar.inc(1);
}

プロンプトと確認

Python：

confirm = typer.confirm("Are you sure?")
if not confirm:
    raise typer.Abort()

Go：

reader := bufio.NewReader(os.Stdin)
fmt.Print("Are you sure? (y/n): ")
response, _ := reader.ReadString('\n')

Rust：

use dialoguer::Confirm;
if Confirm::new().with_prompt("Are you sure?").interact()? {
    // Proceed
}

シェル補完

補完の生成

Python（Typer）：

_MYAPP_COMPLETE=bash_source myapp > ~/.myapp-complete.bash
_MYAPP_COMPLETE=zsh_source myapp > ~/.myapp-complete.zsh

Go（Cobra）：

rootCmd.AddCommand(&cobra.Command{
    Use:   "completion [bash|zsh|fish|powershell]",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        switch args[0] {
        case "bash":
            rootCmd.GenBashCompletion(os.Stdout)
        case "zsh":
            rootCmd.GenZshCompletion(os.Stdout)
        }
    },
})

Rust（clap）：

use clap_complete::{generate, shells::Bash};
generate(Bash, &mut Cli::command(), "myapp", &mut io::stdout())

インストール手順については、references/shell-completion.md を参照してください。

配布とパッケージ化

Python（PyPI）

pyproject.toml：

[project]
name = "myapp"
version = "1.0.0"
scripts = { myapp = "myapp.cli:app" }

公開：

pip install build twine
python -m build
twine upload dist/*

Go（Homebrew）

Formula：

class Myapp < Formula
  desc "My CLI application"
  url "https://github.com/user/myapp/archive/v1.0.0.tar.gz"

  def install
    system "go", "build", "-o", bin/"myapp"
  end
end

Rust（Cargo）

公開：

cargo login
cargo publish

インストール：

cargo install myapp

バイナリリリースを含む、包括的なパッケージ化戦略については、references/distribution.md を参照してください。

ベストプラクティス

CLI 共通の規約

必ず用意するもの：

• 使用方法を表示する --help と -h
• バージョンを表示する --version と -V
• 対処方法がわかる、明確なエラーメッセージ

引数の処理：

• オプションと位置引数を分けるために -- 区切り文字を使用します
• 短縮形（-v）と長形式（--verbose）の両方をサポートします
• すべてのユーザー入力を検証し、サニタイズします

エラー処理：

• 成功時の終了コードは 0
• 一般的なエラー時の終了コードは 1
• 使用方法のエラー時の終了コードは 2
• エラーは stderr に、データは stdout に書き込みます

対話性：

• TTY を検出します（対話入力かパイプ入力かを判別します）
• 自動化でプロンプトを省略できるよう、--yes／--force を用意します
• 2 秒を超える操作では進捗を表示します

設定のベストプラクティス

ファイル形式：

• YAML、TOML、JSON のいずれかを一貫して使用します
• 環境（dev、staging、prod）ごとにファイルを分けます
• --check-config を使い、CI/CD で設定を検証します

シークレット管理：

• シークレットを設定ファイルに絶対にコミットしないでください
• 環境変数またはシークレットマネージャーを使用します
• 必須の環境変数を文書化します

優先順位：

• CLI 引数 > 環境変数 > 設定ファイル > デフォルト値
• ヘルプテキストで優先順位を文書化します
• 有効な設定を表示する --print-config を用意します

他のスキルとの連携

testing-strategies：

• モックとフィクスチャを使った CLI テスト
• エンドツーエンドのワークフローの統合テスト
• examples/python/test_cli.py を参照してください

building-ci-pipelines：

• 複数のプラットフォーム向けのバイナリビルド
• GitHub Actions によるリリースの自動化
• references/distribution.md を参照してください

api-patterns：

• API クライアント CLI の構築
• 認証とトークン管理
• API レスポンスのフォーマット

secret-management：

• 認証情報の安全な保存
• 環境変数との連携
• Vault／シークレットマネージャーとの連携

リファレンスファイル

意思決定のためのフレームワーク：

• framework-selection.md - 選択するフレームワーク
• argument-patterns.md - 引数、オプション、フラグの違い
• subcommand-design.md - コマンド階層の構成

実装ガイド：

• configuration-management.md - 設定ファイルと優先順位
• output-formatting.md - 人間向けと機械可読形式の出力
• shell-completion.md - 補完の生成
• distribution.md - CLI のパッケージ化とリリース

コード例：

• examples/python/ - Typer の例（基本、サブコマンド、設定、対話型）
• examples/go/ - Cobra の例（基本、サブコマンド、Viper との連携）
• examples/rust/ - clap の例（derive、builder、サブコマンド）

クイックリファレンス

フレームワークの推奨：

• Python：Typer（モダン）または Click（実績あり）
• Go：Cobra（エンタープライズ向け）または urfave/cli（シンプル）
• Rust：clap v4（derive または builder）

一般的なパターン：

• 引数：主要な入力（最大 2～3 個）
• オプション：値を持つ名前付きパラメーター
• フラグ：ブール値の切り替え
• サブコマンド：関連する操作をまとめる
• 設定：CLI 引数 > 環境変数 > ファイル > デフォルト

出力の標準：

• デフォルト：人間が読みやすい形式（色付き、テーブル）
• 機械向け：--output フラグによる JSON／YAML
• エラー：stderr、データ：stdout
• 終了コード：0 = 成功、1 = エラー、2 = 使用方法

配布：

• Python：PyPI（pip install）
• Go：Homebrew、バイナリリリース
• Rust：Cargo（cargo install）、バイナリリリース