背景・目的

最近、CobraというCLIアプリケーションを作成するライブラリを知りました。
今回、整理し簡単に試してみたいと思います。

まとめ

下記に特徴を整理します。

特徴	説明
Cobraとは	強力な最新の CLI アプリケーションを作成するためのライブラリ Kubernetes、Hugo、GitHub CLI など、多くの Go プロジェクトで使用されている
概要	git や go ツールに似た強力な最新の CLI インターフェースを作成するためのシンプルなインターフェースを提供するライブラリ
提供する機能	・簡単なサブコマンドベースの CLI: アプリサーバー、アプリフェッチなど・完全にPOSIX準拠のフラグ（短いバージョンと長いバージョンを含む）・ネストされたサブコマンド・グローバル、ローカル、カスケードフラグ・インテリジェントな提案・コマンドとフラグの自動ヘルプ生成・サブコマンドのヘルプのグループ化・-h、--help などのヘルプフラグの自動認識・アプリケーション用のシェルのオートコンプリートを自動的に生成・コマンドエイリアスを使用すると、変更しても壊れることはない・独自のヘルプや使用方法などを定義できる柔軟性・Twelve-Factor AppのViperとの統合
コンセプト	コマンド、引数、フラグの構造に基づいて構築されている
ライセンス	Apache 2.0

概要

下記を基に整理します。

Cobra is a library for creating powerful modern CLI applications.
Cobra is used in many Go projects such as Kubernetes, Hugo, and GitHub CLI to name a few. This list contains a more extensive list of projects using Cobra.

Cobra は、強力な最新の CLI アプリケーションを作成するためのライブラリ
Cobra は、Kubernetes、Hugo、GitHub CLI など、多くの Go プロジェクトで使用されている
他のCobraを使用するプロジェクトはこちらのリストを参照

Overview

Cobra is a library providing a simple interface to create powerful modern CLI interfaces similar to git & go tools.

git や go ツールに似た強力な最新の CLI インターフェースを作成するためのシンプルなインターフェースを提供するライブラリ

Cobra provides:

Easy subcommand-based CLIs: app server, app fetch, etc.

Fully POSIX-compliant flags (including short & long versions)

Nested subcommands

Global, local and cascading flags

Intelligent suggestions (app srver... did you mean app server?)

Automatic help generation for commands and flags

Grouping help for subcommands

Automatic help flag recognition of -h, --help, etc.

Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)

Automatically generated man pages for your application

Command aliases so you can change things without breaking them

The flexibility to define your own help, usage, etc.

Optional seamless integration with viper for 12-factor apps

Cobraが下記を提供している

Concepts

Cobra is built on a structure of commands, arguments & flags.
Commands represent actions, Args are things and Flags are modifiers for those actions.
The best applications read like sentences when used, and as a result, users intuitively know how to interact with them.
The pattern to follow is APPNAME VERB NOUN --ADJECTIVE or APPNAME COMMAND ARG --FLAG.
A few good real world examples may better illustrate this point.
In the following example, 'server' is a command, and 'port' is a flag:

Cobra は、コマンド、引数、フラグの構造に基づいて構築されている
コマンドはアクションを表し、引数は物、フラグはそれらのアクションの修飾子
最高のアプリケーションは、使用時に文章のように読み取られ、その結果、ユーザーは直感的に操作方法を知ることができる
従うべきパターンは、APPNAME VERB NOUN --ADJECTIVE または APPNAME COMMAND ARG --FLAG
例):「server」はコマンド、「port」はフラグ
```
hugo server --port=1313
```
例):このコマンドでは、Git に URL をそのままクローンするように指示している
```
git clone URL --bare
```

Commands

Command is the central point of the application. Each interaction that the application supports will be contained in a Command. A command can have children commands and optionally run an action.

コマンドはアプリケーションの中心点
アプリケーションがサポートする各インタラクションはコマンドに含まれる
コマンドには子コマンドを含めることができ、オプションでアクションを実行できる

Flags

A flag is a way to modify the behavior of a command. Cobra supports fully POSIX-compliant flags as well as the Go flag package. A Cobra command can define flags that persist through to children commands and flags that are only available to that command.

フラグは、コマンドの動作を変更する方法
Cobra は、Go フラグパッケージだけでなく、POSIX に完全準拠したフラグもサポートしている
Cobra コマンドでは、子コマンドにまで存続するフラグと、そのコマンドでのみ使用可能なフラグを定義できる

Flag functionality is provided by the pflag library, a fork of the flag standard library which maintains the same interface while adding POSIX compliance.

フラグ機能は、POSIX 準拠を追加しながら同じインターフェースを維持するフラグ標準ライブラリのフォークである pflag ライブラリによって提供される

実践

前提

下記を前提としています。

VSCode
MacOS:Sonoma
Go:1.23.0

セットアップ

プロジェクトの作成

ディレクトリを作成します
```
% mkdir go-cli
% 
```
作成したディレクトリをVSCodeのワークスペースに追加します

プロジェクトを初期化します

% cd go-cli
% go mod init go-cli
go: creating new go.mod: module go-cli
% cat go.mod 
module go-cli

go 1.23.0
%

Cobraのセットアップ

Cobraをインストールします

% go get -u github.com/spf13/cobra@latest
go: downloading github.com/spf13/cobra v1.8.1
go: downloading github.com/inconshreveable/mousetrap v1.1.0
go: downloading github.com/spf13/pflag v1.0.5
go: added github.com/inconshreveable/mousetrap v1.1.0
go: added github.com/spf13/cobra v1.8.1
go: added github.com/spf13/pflag v1.0.5
% ls -ltr
total 16
-rw-r--r--  1 XXXX  XXXX  181 10 21 22:32 go.mod
-rw-r--r--  1 XXXX  XXXX  896 10 21 22:32 go.sum
% cat go.mod 
module go-cli

go 1.23.0

require (
        github.com/inconshreveable/mousetrap v1.1.0 // indirect
        github.com/spf13/cobra v1.8.1 // indirect
        github.com/spf13/pflag v1.0.5 // indirect
)
%

CLIアプリケーションのベースを自動生成するために、CLIもインストールします

% go install github.com/spf13/cobra-cli@latest
go: downloading github.com/spf13/cobra-cli v1.3.0
go: downloading github.com/spf13/cobra v1.3.0
go: downloading github.com/spf13/viper v1.10.1
go: downloading github.com/spf13/jwalterweatherman v1.1.0
go: downloading github.com/magiconair/properties v1.8.5
go: downloading github.com/mitchellh/mapstructure v1.4.3
go: downloading github.com/spf13/afero v1.6.0
go: downloading github.com/fsnotify/fsnotify v1.5.1
go: downloading github.com/spf13/cast v1.4.1
go: downloading github.com/subosito/gotenv v1.2.0
go: downloading gopkg.in/ini.v1 v1.66.2
go: downloading github.com/hashicorp/hcl v1.0.0
go: downloading github.com/pelletier/go-toml v1.9.4
go: downloading gopkg.in/yaml.v2 v2.4.0
go: downloading golang.org/x/sys v0.0.0-20211210111614-af8b64212486
go: downloading golang.org/x/text v0.3.7
%

PATHを確認します
```
% go env GOPATH
/Users/XXXX/go
% 
```

.zshrcにPATHを追加します

export PATH="$PATH:$(go env GOPATH)/bin"

読み込みます
```
source ~/.zshrc
```

実行できました

% cobra-cli -h   
Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.

Usage:
  cobra-cli [command]

Available Commands:
  add         Add a command to a Cobra Application
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  init        Initialize a Cobra Application

Flags:
  -a, --author string    author name for copyright attribution (default "YOUR NAME")
      --config string    config file (default is $HOME/.cobra.yaml)
  -h, --help             help for cobra-cli
  -l, --license string   name of license for the project
      --viper            use Viper for configuration

Use "cobra-cli [command] --help" for more information about a command.
%

Cobraを使ったCLIアプリケーションの作成

プロジェクトの初期化

下記のコマンドを実行し、初期化します

% cobra-cli init
Your Cobra application is ready at
/Users/XXXX/XXXX/go-cli
%

LICENSE、cmdディレクトリ、main.goオブジェクトが生成されました

% ls -l
total 24
-rw-r--r--  1 XXX  XXX    0 10 21 22:53 LICENSE
drwxr-x--x  3 XXX  XXX   96 10 21 22:53 cmd
-rw-r--r--  1 XXX  XXX  181 10 21 22:32 go.mod
-rw-r--r--  1 XXX  XXX  896 10 21 22:32 go.sum
-rw-r--r--  1 XXX  XXX  117 10 21 22:53 main.go
%

main.goを確認してみます

% cat main.go 
/*
Copyright © 2024 NAME HERE <EMAIL ADDRESS>

*/
package main

import "go-cli/cmd"

func main() {
        cmd.Execute()
}
%

cmd/root.goを確認してみます

% cat cmd/root.go 
/*
Copyright © 2024 NAME HERE <EMAIL ADDRESS>

*/
package cmd

import (
        "os"

        "github.com/spf13/cobra"
)



// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
        Use:   "go-cli",
        Short: "A brief description of your application",
        Long: `A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:

Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.`,
        // Uncomment the following line if your bare application
        // has an action associated with it:
        // Run: func(cmd *cobra.Command, args []string) { },
}

// Execute adds all child commands to the root command and sets flags appropriately.
// This is called by main.main(). It only needs to happen once to the rootCmd.
func Execute() {
        err := rootCmd.Execute()
        if err != nil {
                os.Exit(1)
        }
}

func init() {
        // Here you will define your flags and configuration settings.
        // Cobra supports persistent flags, which, if defined here,
        // will be global for your application.

        // rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.go-cli.yaml)")

        // Cobra also supports local flags, which will only run
        // when this action is called directly.
        rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}
%

helloコマンドの追加

コマンドを追加します

% cobra-cli add hello
hello created at /Users/XXXX/XXXX/go-cli
%

helloファイルが追加されました

% ls -l cmd 
total 16
-rw-r--r--  1 XXXX  XXXX  1072 10 21 23:00 hello.go
-rw-r--r--  1 XXXX  XXXX  1438 10 21 22:53 root.go
%

下記のように編集します

/*
Copyright © 2024 NAME HERE <EMAIL ADDRESS>
*/
package cmd

import (
	"fmt"

	"github.com/spf13/cobra"
)

var name string

// helloCmd represents the hello command
var helloCmd = &cobra.Command{
	Use:   "hello",
	Short: "Say hello to someone",
	Long:  `This command allows you to say hello to someone by specifying their name.`,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Printf("Hello, %s!\n", name)
	},
}

func init() {
	rootCmd.AddCommand(helloCmd)
	helloCmd.Flags().StringVarP(&name, "name", "n", "World", "Name of the person to greet")
}

実行します。想定通りの結果です

% go run main.go hello --name Taro
Hello, Taro!
%

ビルド

バイナリファイルを生成し、実行します

go buildコマンドを実行します
```
% go build -o hello 
```

確認します

% ls -l            
total 10680
-rw-r--r--  1 XXXX  XXXX        0 10 21 22:53 LICENSE
drwxr-x--x  4 XXXX  XXXX      128 10 21 23:00 cmd
-rw-r--r--  1 XXXX  XXXX      181 10 21 23:13 go.mod
-rw-r--r--  1 XXXX  XXXX      896 10 21 22:32 go.sum
-rwxr-xr-x  1 XXXX  XXXX  5452224 10 21 23:21 hello
-rw-r--r--  1 XXXX  XXXX      117 10 21 22:53 main.go
%

実行できました

% ./hello hello --name Jiro
Hello, Jiro!
%

フラグをトップレベルコマンドに適用する

hello --nameの形式で実行できるようにします。

hello.goを削除します
```
% rm cmd/hello.go
```

root.goを修正します

/*
Copyright © 2024 NAME HERE <EMAIL ADDRESS>
*/
package cmd

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
)

var name string

// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
	Use:   "hello",
	Short: "Say hello to someone",
	Long:  `This application allows you to say hello to a person by specifying their name.`,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Printf("Hello, %s!\n", name)
	},
}

func Execute() {
	err := rootCmd.Execute()
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

func init() {
	rootCmd.Flags().StringVarP(&name, "name", "n", "World", "Name of the person to greet")
}

できました

% ls -l
total 10680
-rw-r--r--  1 XXXX  XXXX        0 10 21 22:53 LICENSE
drwxr-x--x  3 XXXX  XXXX       96 10 21 23:36 cmd
-rw-r--r--  1 XXXX  XXXX      181 10 21 23:13 go.mod
-rw-r--r--  1 XXXX  XXXX      896 10 21 22:32 go.sum
-rwxr-xr-x  1 XXXX  XXXX  5452128 10 21 23:37 hello
-rw-r--r--  1 XXXX  XXXX      117 10 21 22:53 main.go
%

実行します。想定通りの結果です
```
% ./hello --name Jiro
Hello, Jiro!
% 
```

考察

今回、Cobraの基本的な特徴を整理し、簡単な動作確認を行いました。シンプルなCLIツールを作成するところまで進めましたが、今後はサブコマンドを追加したり、より複雑な機能を持つCLIツールの実装を試したいと思います。

参考