Go における CLI 開発用ライブラリ spf13/cobra & urfave/cli の紹介と比較
はじめに
こんにちは、くるふとです。
ナビタイムジャパンでは、時刻表 API や地図描画 API の 開発・運用業務を主に担当しています。
Go で CLI を開発する際に有力なライブラリとして、 spf13/cobra と urfave/cli が挙げられます。
どちらも利用事例の多いライブラリで、CLI の開発に役立つ多くの機能がサポートされています。もちろん当社でも両者共に採用実績があります。
今回の記事ではこの２つのライブラリを機能ごとに比較してみようと思います。
注意事項
両ライブラリの特徴、機能ごとの比較、おすすめの利用シーン等をまとめていますが、どちらが優れている、劣っているという結論を出す意図はありません。あらかじめご了承いただけると幸いです。
各ライブラリの使い方
以下のようなサンプル CLI を想定して、それぞれ使い方、サンプルコードを紹介します。
サブコマンドとして example hoge 、オプションとして --bool と --string を持つ CLI です。
サンプル CLI 実行例
$ example hoge --help
NAME:
example hoge - execute hoge command
USAGE:
example hoge [command options]
OPTIONS:
--bool, -b enable a flag (default: false)
--string value, -s value specify b flag value
--help, -h show help
$ example hoge
This is hoge-command.
$ example hoge --bool
This is hoge-command.
--bool is enabled.
$ example hoge --bool --string "fuga"
This is hoge-command.
--bool is enabled.
--string specifies "fuga".spf13/cobra
install 手順
$ go get -u github.com/spf13/cobra@latest # ライブラリのインストール
$ go install github.com/spf13/cobra-cli@latest # ジェネレータのインストールcobra-cli の実行手順
$ cobra-cli init
Your Cobra application is ready at
/*****/**********/**********/myappcobra-cli init コマンドでディレクトリに main.go および cmd/root.go が作成されます。
main.go
/*
Copyright © 2024 NAME HERE <EMAIL ADDRESS>
*/
package main
import "sandboxgocobra/cmd"
func main() {
cmd.Execute()
}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: "sandboxgocobra",
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/.sandboxgocobra.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")
}サブコマンドは cobra-cli add で追加できます。
$ cobra-cli add hogeコマンドを実行すると cmd/hoge.go が作成されます。
cmd/hoge.go
/*
Copyright © 2024 NAME HERE <EMAIL ADDRESS>
*/
package cmd
import (
"fmt"
"github.com/spf13/cobra"
)
// hogeCmd represents the hoge command
var hogeCmd = &cobra.Command{
Use: "hoge",
Short: "A brief description of your command",
Long: `A longer description that spans multiple lines and likely contains examples
and usage of using your command. 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.`,
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("hoge called")
},
}
func init() {
rootCmd.AddCommand(hogeCmd)
}ここまでが雛形の生成手順です。
作成されたファイルを整理すると、以下のようになります。
$ tree
.
├── LICENSE
├── cmd
│ ├── hoge.go
│ └── root.go
├── go.mod
├── go.sum
└── main.go
2 directories, 6 files最後に、今回の仕様に合わせて cmd/hoge.go を実装していきます。
以下は実装例です。
cmd/hoge.go
package cmd
import (
"fmt"
"github.com/spf13/cobra"
)
func init() {
var boolFlag bool
var stringFlag string
// hogeCmd represents the hoge command
var hogeCmd = &cobra.Command{
Use: "hoge",
Short: "execute hoge command",
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("This is hoge-command.")
if boolFlag {
fmt.Println("--bool is enabled.")
}
if stringFlag != "" {
fmt.Printf("--string specifies \"%s\".\n", stringFlag)
}
},
}
hogeCmd.Flags().BoolVarP(&boolFlag, "bool", "b", false, "enable a flag")
hogeCmd.Flags().StringVarP(&stringFlag, "string", "s", "", "specify b flag value")
rootCmd.AddCommand(hogeCmd)
}urfave/cli
urfave/cli は v1, v2, v3 が存在しますが、今回は v2 をベースに解説します。
（v3 はまだ開発段階のバージョンのため今回の解説からは外します）
install 手順
$ go get -u github.com/urfave/cli/v2urfave/cli はジェネレータはないため、そのまま実装します。
以下実装例です。
main.go
package main
import (
"fmt"
"log"
"os"
"github.com/urfave/cli/v2"
)
func main() {
app := &cli.App{
Name: "example",
Usage: "a simple CLI application",
Commands: []*cli.Command{
{
Name: "hoge",
Usage: "execute hoge command",
Flags: []cli.Flag{
&cli.BoolFlag{
Name: "bool",
Aliases: []string{"b"},
Usage: "enable a flag",
},
&cli.StringFlag{
Name: "string",
Aliases: []string{"s"},
Usage: "specify b flag value",
},
},
Action: func(c *cli.Context) error {
fmt.Println("This is hoge-command.")
if c.Bool("bool") {
fmt.Println("--bool is enabled.")
}
if b := c.String("string"); b != "" {
fmt.Printf("--string specifies \"%s\".\n", b)
}
return nil
},
},
},
}
err := app.Run(os.Args)
if err != nil {
log.Fatal(err)
}
}各機能ごとの比較表
主な機能の詳細についても説明します。
Flag
コマンドラインの flag について、両パッケージとも複数の型をサポートしています。
cobra は spf13/pflag の flag を用いています。spf13/pflag で利用できる flag の型は以下で確認できます。
使用できる flag は以下で確認できます。
ジェネレータ
spf13/cobra では cobra-cli というジェネレータが用意されています。
「各ライブラリの使い方」の章でも紹介しましたが、このコマンドを利用することにより、 CLI の雛形を生成することができます。
urfave/cli には残念ながらジェネレータに相当するものはありません。
ドキュメントページ作成
こちらも spf13/cobra のみ機能となります。
spf13/cobra では CLI のドキュメントページを生成する機能が用意されています。
例えば、下記のコードは Markdown 方式のドキュメントファイルをローカルの tmp 配下に出力します。ドキュメントはサブコマンドのものも一緒に作成されます。
cmd/root.go
package cmd
import (
"log"
"os"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)
var rootCmd = &cobra.Command{
Use: "example",
Short: "This is sample CLI.",
Long: `This is sample CLI.
Created for the explanation of spf13/cobra.`,
}
func Execute() {
err := rootCmd.Execute()
if err != nil {
os.Exit(1)
}
}
func init() {
// ./tmp 配下に markdown 形式のファイルを作成する
err := doc.GenMarkdownTree(rootCmd, "./tmp")
if err != nil {
log.Fatal(err)
}
}tmp/example.md
## example
This is sample CLI.
### Synopsis
This is sample CLI.
Created for the explanation of spf13/cobra.
### Options
```
-h, --help help for example
```
### SEE ALSO
* [example hoge](example_hoge.md) - execute hoge command
###### Auto generated by spf13/cobra on 9-Aug-2024tmp/example_hoge.md
## example hoge
execute hoge command
```
example hoge [flags]
```
### Options
```
-b, --bool enable a flag
-h, --help help for hoge
-s, --string string specify b flag value
```
### SEE ALSO
* [example](example.md) - This is sample CLI.
###### Auto generated by spf13/cobra on 9-Aug-2024現在は下記のフォーマットがサポートされています。
Man pages
Markdown
reStructuredText
Yaml
両ライブラリの特徴まとめ
機能ごとの比較をふまえて、両ライブラリのメリット、デメリットをまとめてみました。
spf13/cobra
メリット
generator （cobra-cli）を用いたコマンド実装
ドキュメントページ生成機能
CLI の実装に役立つ便利な機能が多く備わっている
デメリット
機能が豊富な分、関連ライブラリの構成がやや複雑
pflag, viper など
おすすめ利用シーン
リッチな機能を持つ CLI を実装したい時
urfave/cli
メリット
シンプルなライブラリとなっている
ドキュメントページがわかりやすい
デメリット
機能面が cobra に比べてやや乏しい
おすすめ利用シーン
シンプルな CLI の実装したい時
Go で初めて CLI 開発をしたい時
さいごに
いかがでしたでしょうか？
個人的には、シンプルな CLI を開発したい時は urfave/cli、リッチな機能を持つ CLI を開発したい時は spf13/cobra という使い分けが良いと感じました。
どちらも使いやすいライブラリなので、両方試してみるのをお勧めします。