ペルソナ: Unix シェルのような使い心地を実現するコマンドツリーを構築する Go CLI エンジニアです。ユーザー向けのインターフェースを最初に設計し、その後、動作を適切なフックに組み込みます。

モード:

• Build — ゼロからの新規 CLI 作成: コマンドツリーのセットアップ、フックの配線、フラグのセクションを順序立てて進めます。
• Extend — 既存 CLI への機能追加: 現在のコマンドツリーを最初に読んでから、既存の構造に一貫した変更を適用します。
• Review — 既存 CLI の監査: 「よくある間違い」表を確認し、RunE の使用方法、OutOrStdout() を検証し、フックチェーンの順序とArgs検証を確認します。

Go での spf13/cobra を使用した CLI コマンドツリー

Cobra は Go CLI アプリケーションの事実上の標準です。コマンド/サブコマンドツリー、フラグパース (pflag 経由)、Args検証、シェル補完生成、ドキュメント生成を提供します。ただし、設定のレイヤー化は処理しません — これは viper の仕事です。

公式リソース:

• pkg.go.dev/github.com/spf13/cobra
• github.com/spf13/cobra
• cobra.dev

このスキルは完全ではありません。詳細情報については、ライブラリのドキュメントとコード例を参照してください。Context7 は検出プラットフォームとして役立ちます。

go get github.com/spf13/cobra@latest

Cobra vs. viper

これらのライブラリは根本的に異なることを行い、独立して使用できます。

対象	cobra	viper
管轄	コマンドツリー、フラグ、Args検証、補完	設定値の解決
ユーザー向け?	Yes — サブコマンド、フラグ、ヘルプテキスト	No — 純粋なキー・バリュー リゾルバー
他方なしで使用可能?	Yes — フラグのみの CLI は cobra だけで十分	Yes — YAML + env を読む長実行サービスは viper だけで十分
統合シーム	BindPFlag 経由で viper に pflag.Flag を渡す	cobra フラグを最優先層として扱う

cobra のみを使用 する場合は、バイナリがフラグと Args を受け取るが、設定ファイルや環境解決が不要な場合です。viper のみを使用 する場合は、長実行サービスが YAML + env から設定を読み取るが、CLI サブコマンドがない場合です。両方が必要な場合は両方を使用し、ルートコマンド上の PersistentPreRunE でバインドします。

→ この統合の viper 側については、samber/cc-skills-golang@golang-spf13-viper スキルを参照してください。

コマンドツリー

すべての cobra CLI にはルートコマンドと、AddCommand で登録された 0 個以上のサブコマンドが存在します。ルートコマンド名はバイナリ名です。

var rootCmd = &cobra.Command{
    Use:          "myapp",
    Short:        "One-line summary",
    SilenceUsage: true,  // ✓ prevents usage wall on every error
    SilenceErrors: true, // ✓ lets you control error output format
}

AddGroup を使用してヘルプ出力でサブコマンドにラベル付けします — グループを登録してから、それらを参照する AddCommand 呼び出しを行ってください。cobra は遡ってグループを割り当てることはありません。

Run* ファミリー

Cobra コマンドには、順序に従って実行される 5 つのランフックがあります:

PersistentPreRunE → PreRunE → RunE → PostRunE → PersistentPostRunE

常に *E バリアントを使用してください — *E でないフォームはエラーを返すことができません。重要なルール:

• ルート上の PersistentPreRunE はすべてのサブコマンド前に実行されます — 設定初期化と認証チェックに使用してください。
• 子の PersistentPreRunE は親のものを完全に置き換えます — 両方が必要な場合は親を明示的に呼び出してください。
• PostRunE は RunE が成功した場合のみ実行されます。

ライフサイクル全体と継承ルールについては、commands-and-args.md を参照してください。

Args 検証

Cobra は RunE が実行される前に位置引数を検証します。RunE 内に len(args) チェックを書かないでください — cobra の標準エラーメッセージと引数カウント追跡をバイパスしてしまいます。

ビルトイン: NoArgs、ExactArgs(n)、MinimumNArgs(n)、MaximumNArgs(n)、RangeArgs(min,max)、OnlyValidArgs、ExactValidArgs(n)。MatchAll(v1, v2) で構成します。カスタム検証: func(cmd *cobra.Command, args []string) error。

完全な検証セット、例、MatchAll パターンについては、commands-and-args.md を参照してください。

フラグの入門

Cobra はフラグのパースを pflag に委譲します。永続フラグ (PersistentFlags()) はすべてのサブコマンドに継承されます。ローカルフラグ (Flags()) は宣言命令のみに適用されます。

rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file path") // inherited by all subcommands
serveCmd.Flags().IntVar(&port, "port", 8080, "listen port")                     // local to serveCmd only
serveCmd.MarkFlagRequired("port")
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")

pflag タイプ、カスタムフラグ値、フラググループ、viper バインディングについては、flags.md を参照してください。

補完の入門

Cobra はシェル補完を自動的に生成します。以下で拡張します:

• ValidArgs []string — 静的な位置引数補完。
• ValidArgsFunction — 動的: func(cmd, args, toComplete string) ([]string, ShellCompDirective)。ファイル フォールバックを抑制するには ShellCompDirectiveNoFileComp を返します。
• RegisterFlagCompletionFunc(name, fn) — フラグ値の補完。

ShellCompDirective 値、アノテーション、テストについては、completions.md を参照してください。

コマンドのテスト

コマンドをプログラムで実行してテストします。コマンドハンドラで os.Stdout / os.Stderr を直接使用しないでください — テストが出力をリダイレクトできるように cmd.OutOrStdout() / cmd.ErrOrStderr() を使用してください。

func TestServeCmd(t *testing.T) {
    buf := new(bytes.Buffer)
    rootCmd.SetOut(buf)
    rootCmd.SetArgs([]string{"serve", "--port", "9090"})
    require.NoError(t, rootCmd.Execute())
    assert.Contains(t, buf.String(), "listening on :9090")
}

Cobra は Execute() 呼び出し間でフラグ状態を蓄積します — テストごとに新しいコマンドツリーを構築します。分離パターン、ゴールドファイル、補完のテストについては、testing.md を参照してください。

ベストプラクティス

1. 常に RunE を使用し、Run は使用しないでください — Run はエラーを返せません。唯一の脱出手段は os.Exit またはパニックであり、defer をバイパスします。
2. 設定初期化を PersistentPreRunE に配置します — すべてのサブコマンド前に実行されます。viper バインディングと認証チェックに適切な場所です。
3. 位置引数を Args で検証し、RunE 内では検証しません — Args は cobra の標準エラーメッセージを提供します。MatchAll は検証を構成します。
4. すべての出力に cmd.OutOrStdout() / cmd.ErrOrStderr() を使用します — 直接 os.Stdout 書き込みはテストで取得できません。
5. テストごとにコマンドツリーを再作成します — cobra は同じインスタンス上の Execute() 呼び出し間でフラグ状態を蓄積します。

よくある間違い

間違い	失敗する理由	修正方法
Run の代わりに RunE を使用	エラーを返せません — 唯一の脱出手段は os.Exit またはパニックであり、defer をバイパスします	RunE を使用します — エラーを返し、cobra に終了を処理させます
RunE 内に len(args) チェックを記述	cobra の標準エラーメッセージ ("accepts 1 arg, received 2") をバイパスします	コマンド上で Args: cobra.ExactArgs(1) を宣言します
直接 os.Stdout に書き込む	テストが出力を取得できません — OS レベルのファイルハンドルはリダイレクトできません	cmd.OutOrStdout() / cmd.ErrOrStderr() を使用します
子の PersistentPreRunE が親の沈黙を落とす	Cobra はチェーンしません — 子フックは親のフック全体を置き換えます	子フックから parent.PersistentPreRunE(cmd, args) を呼び出します
テスト間でルートコマンドを再利用	Cobra はフラグ状態を蓄積します。2 番目の Execute() は最初のフラグを見ます	テストごとに新しいコマンドツリーを構築します

参考文献

• commands-and-args.md — 完全な PreRun*/PostRun* チェーン、すべての Args 検証、PersistentPreRunE 継承ルール
• flags.md — pflag タイプ、必須/排他的/oneRequired グループ、カスタム値タイプ、viper バインディング
• completions.md — ShellCompDirective セット、アノテーション ベースの補完、補完のテスト
• generators.md — man ページ、markdown、YAML、RST ドキュメント生成。cobra-cli スキャフォルダー
• testing.md — 分離パターン、ゴールドファイル、補完のテスト、テーブル駆動コマンドテスト

相互参照

• → 一般的な CLI アーキテクチャについては、samber/cc-skills-golang@golang-cli スキルを参照してください — プロジェクトレイアウト、終了コード、シグナル処理、I/O パターン
• → cobra と並行して設定レイヤー化する場合は、samber/cc-skills-golang@golang-spf13-viper スキルを参照してください (フラグ → env → ファイル → デフォルト優先度)
• → 一般的な Go テストパターンについては、samber/cc-skills-golang@golang-testing スキルを参照してください

spf13/cobra でバグまたは予期しない動作が発生した場合は、https://github.com/spf13/cobra/issues で issue をオープンしてください。