🐺

Go Cobra のざっくりとした使い方

2024/04/03に公開

はじめに

本記事は、GoでCLIツールを作成するためのcobraについて
使い方などサッとまとめてみた記事となります。

https://github.com/spf13/cobra

前提

  • goinstallされていること
  • cobraでプロジェクトが作成されていること

宣伝

今回まとめるにあたり、作成したauthorコマンド
gitアカウントに紐づくcommit履歴を、複数リポジトリまたいで検索するコマンドです。

https://github.com/Pianoopera/author

cobra の概要

cobra は各コマンドに対してRun関数が用意されており、コマンドが呼び出されたときに実行されるロジックを記述します。

func(cmd *cobra.Command, args []string) {
    // コマンドが呼び出されたときの処理
}

コマンドごとにフラグも定義することも可能。
フラグは、コマンドラインオプションとして機能し、ユーザーがコマンドを実行する際に追加の情報を提供できるようにします。

var yourCommand = &cobra.Command{
    Use:   "yourCommand",
    Short: "Your command description",
    Long: `A longer description that spans multiple lines and likely contains examples and usage of using your command.`,
    Run: func(cmd *cobra.Command, args []string) {
        // コマンドが呼び出されたときの処理
    },
}

func init() {
    rootCmd.AddCommand(yourCommand)
    // ここでフラグを定義
    yourCommand.Flags().StringP("flagname", "f", "defaultValue", "Flag description")
}

アプリケーションの開発が完了したら、通常のGoアプリケーションと同様にビルドして実行します。

go build
./yourAppName

cobraの仕様について

  • Use:コマンド名を入力します。
  • Short: コマンドの短い説明で、-helpオプションで表示されます。
  • Long:コマンドの詳細な説明を提供します。-helpオプションで表示され、Short説明よりも多くの情報を含むことができます。
var yourCommand = &cobra.Command{
    Use:   "yourCommand",
    Short: "Your command description",
    Long: `A longer description that spans multiple lines and likely contains examples and usage of using your command.`,
    Run: func(cmd *cobra.Command, args []string) {
        // コマンドが呼び出されたときの処理
    },
}

func init() {
    rootCmd.AddCommand(yourCommand)
    // ここでフラグを定義
    yourCommand.Flags().StringP("flagname", "f", "defaultValue", "Flag description")
}

サブコマンド

コマンドを階層的に組織化することができます。つまり、コマンドにサブコマンドを追加し、それぞれに独自のフラグ、引数、説明を設定することが可能です。

コマンドライン自動補完

bash、zsh、fish、およびPowerShellのためのコマンドライン自動補完スクリプトを生成する機能を提供しているため、あっという間に利用することが可能です。

エラーハンドリング

cobraでは、Argsフィールドを使用してコマンドに渡された引数を検証します。

このフィールドは、cobra.Command構造体内で引数を検証する関数を設定します。

var cmd = &cobra.Command{
    Use:   "mycommand",
    Short: "This is my command",
    Args:  cobra.ExactArgs(2), // ちょうど2つの引数が必要
    Run: func(cmd *cobra.Command, args []string) {
        // コマンドのロジック
    },
}

検証が失敗した場合、cobraはエラーメッセージを表示し、コマンドの実行を中止します。この挙動はデフォルトで有効になっており、基本的なフィードバックがユーザーに提供されます。

また、特定の要件に合わせて引数を検証するために、カスタム検証関数を定義することも可能。
この関数は、cobra.PositionalArgs型である必要があり、引数のスライスを受け取り、error型の値を返します。引数が期待通りであればnilを、そうでなければエラーを返します。

func customArgValidation(cmd *cobra.Command, args []string) error {
    if len(args) < 2 {
        return errors.New("このコマンドには少なくとも2つの引数が必要です")
    }
    // その他の検証ロジック
    return nil
}

var cmd = &cobra.Command{
    Use:   "mycommand",
    Short: "This is my command",
    Args:  customArgValidation,
    Run:   func(cmd *cobra.Command, args []string) {
        // コマンドのロジック
    },
}

以上のように、Cobraでは引数の検証とエラーハンドリングを柔軟に行うことができる。

最後に

今回はザッと使い方をまとめてきましたが
少しでも参考にしてなれば幸いです。

余談

コマンドの作成や、初期設定周りはcobra-cliを利用するとサクサク勧められますので合わせておすすめ

https://github.com/spf13/cobra-cli/blob/main/README.md

Discussion