Cobra CLI

Cobra CLI logo
Cobra, basit arayüzlü komut satırı uygulamaları oluşturmanız için güçlü bir pakettir. CLI uygulamanızı kolaylıkla oluşturabilmeniz için aynı zamanda oluşturucu bir cli aracıdır.
Özellikler:
Kolay alt-komut (subcommand) yapısında cli uygulamaları: app server , app fetch gibi,
Tamamen POSIX uyumlu flag'ler (kısa ve uzun versiyonları ile),
İç içe alt-komutlar,
Global, yerel ve cascading (basamaklı) flag'ler,
cobra init appname ve cobra add cmdname gibi komutlarla kolayca yapı oluşturma,
Akıllı öneriler (app servr ... did you mean app server?)
Komutlar ve flag'ler için otomatik yardım oluşturma
Otomatik help flag tanımlaması -h ve --help
Otomatik shell auto-completion oluşturma (bash-zsh-fish-powershell)
Otomatik manual sayfası oluşturma
Komut alias'ları
Kendi yardım ve kullanım bilgilerini tanımlama esnekliği
Kurulumlar
Paketi kurmak için;
go get -u github.com/spf13/[email protected]
CLI aracını kurmak için;
go install github.com/spf13/[email protected]
​
Basit Bir Başlangıç Yapalım
Proje klasörümüzü oluşturduktan sonra,
cobra-cli aracının çalışması için proje klasörümüzün içerisinde eğer go modules kurulmamışsa go mod init <isim> komutunu çalıştırmamız gerekiyor.
cobra-cli init uygulamam veya bulunduğunuz dizinde oluşturmak için uygulamam yerine . (nokta) kullanabilirsiniz.
Bu komuttan sonra aşağıdaki gibi klasör ve dosya yapısı oluşacaktır.
.
├── LICENSE
├── cmd
│   └── root.go
├── go.mod
├── go.sum
└── main.go
​
1 directory, 5 files
Oluşturulan yapıyı incelediğimizde, main.go dosyamız basitçe aşağıdaki gibi görünür.
main.go
package main
​
import "cobra-cli-example/cmd"
​
func main() {
	cmd.Execute()
}
import kısmındaki cobra-cli-example, go module'daki belirlediğimiz isim olduğundan sizde farklı görünecektir. main() fonksiyonu içerisinde alt-paketimiz olan cmd içerisindeki Execute() fonksiyonunu çalıştırıyor. Varsayılan kullanımda tüm flag'ler ve sub-command'ler vs. bu fonksiyonun çalışmasıyla yüklenecek.
cmd klasörünün içerisine baktığımızda, burada root.go isimli dosyamızı görüyoruz. Bu dosyamızın içerisinde cli uygulamamız başlatıldığında herhangi bir komut girilmemiş ise gerçekleşecek işlemleri bulundurabiliriz.
Örnek olarak komut satırı kullanımında;
./cobra-cli-example
veya
go run .
​
root.go dosyasını inceleyelim.
root.go
package cmd
​
import (
	"os"
​
	"github.com/spf13/cobra"
)
​
​
// rootCmd, uygulama alt-komutsuz şekilde çağırıldığında
//gerçekleşecekleri temsil eder.
var rootCmd = &cobra.Command{
	Use:   "cobra-cli-example",
	Short: "uygulamanın kısa bilgisi",
	Long: `uygulamanın uzun bilgilendirme metnini bu kısma girebilirsiniz.`,
}
​
// Execute fonksiyonu tüm komut ve alt-komutları
// uygulama çalıştırıldığında yüklenmesini sağlar
func Execute() {
	err := rootCmd.Execute()
	if err != nil {
		os.Exit(1)
	}
}
​
func init() {
	// init fonksiyonu içerisinde ise komuta bağlı olan
	// alt-komutlarını ve flag'lerini bağlayabilir ve bunlar
	// için özelleştirmelerde bulunabilirsiniz.
	rootCmd.Flags().BoolP("toggle", "t", false, "toggle için yardım mesajı")
}
Bu uygulamayı go run . komutu ile başlattığınızda, aşağıdaki gibi bir sonuç alırsınız.
$ go run .
uygulamanın uzun bilgilendirme metnini bu kısma girebilirsiniz.
Varsayılan olarak rootCmd altındaki Long içerisinde yazdığımız açıklama metni görünür.
Uygulamamız çalıştığında bir işlem gerçekleştirmek istiyorsak, aşağıdaki gibi yapabiliriz.
root.go dosyası içerisinde rootRun isminde bir fonsiyon oluşturalım.
cmd/root.go
func rootRun(cmd *cobra.Command, args []string) {
	fmt.Println("Merhaba Dünya!")
}
Bu fonksiyonumuzun çalıştırılması için oluşturduğumuz rootCmd nesnesine ekleyelim.
cmd/root.go
1
var rootCmd = &cobra.Command{
2
	Use:   "cobra-cli-example",
3
	Short: "uygulamanın kısa bilgisi",
4
	Long:  `uygulamanın uzun bilgilendirme metnini bu kısma girebilirsiniz.`,
5
	Run:   rootRun,
6
}
5. satırda Run alanına çalıştırmak istediğimiz fonksiyonu yazdık.
Uygulamamızı başlattığımızda aşağıdaki gibi bir çıktı ile karşılaşacağız.
$ go run .
Merhaba Dünya!
Böylece rootCmd uzun bilgilendirme metnini görüntülemek yerine artık istediğimiz işlemi yapıyor.
​
Eğer bilgilendirme metnini veya yardım metinlerini görmek istersek, -- help veya -h flag'lerini kullanabiliriz.
$ go run . --help
uygulamanın uzun bilgilendirme metnini bu kısma girebilirsiniz.
​
Usage:
  cobra-cli-example [flags]
​
Flags:
  -h, --help     help for cobra-cli-example
  -t, --toggle   toggle için yardım mesajı
​
Uygulamanın yüklenmesi
Oluşturduğumuz uygulamayı yüklemek için build edebilir veya go install komutu ile yükleyebilirsiniz.
go install ile yükledikten sonra komut bulunamıyorsa, ~/go/bin klasörünü path'e eklemeyi deneyebilirsiniz.
Bir komut ekleyelim
Komut eklemek için tekrardan cobra-cli aracından faydalanabiliriz. Bunun için;
$ cobra-cli add gopher 
gopher created at /xxxxxxx/cobra-cli-example
Bu komut sonrası cmd klasörümüzün içerisinde komuta verdiğimiz isim olan gopher isminde bir go dosyası oluşturulduğunuz göreceksiniz.
Bu dosyayı inceleyelim. Aşağıdaki kodlarda sadeleştirilmiş halini göreceksiniz.
cmd/gopher.go
package cmd
​
import (
	"fmt"
​
	"github.com/spf13/cobra"
)
​
// gopherCmd, gopher komutunu temsil eder.
var gopherCmd = &cobra.Command{
	Use:   "gopher",
	Short: "gopher komutu için kısa tanımlama",
	Long: `gopher komutu için uzun tanımlama metnini buraya girebilirsiniz.`,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("gopher komutu çalıştı")
	},
}
​
func init() {
	// Bu kısımda gopher komutumuzun cli üzerinden çağrılabilmesi için
	// root komutumuza ekliyoruz.
	rootCmd.AddCommand(gopherCmd)
}
Yukarıdaki örnekte run fonksiyonunu direkt olarak gopherCmd içerisinde yazdık. Zaten varsayılan olarak oluşturulduğunda burada yazıyor. Kod düzenini sağlamak için eğer uzun satırlı bir fonksiyon olacaksa ayrı bir yerde yazılması tavsiye edilir.
Aşağıdaki komutla bu işlemi de deneyebiliriz.
$ go run . gopher
gopher komutu çalıştı
Alt-komut ekleme
Yukarıdaki gopher komutuna bir alt komut eklemek istersek, aşağıdaki yöntemi uygulamalıyız.
Öncelikle cobra-cli aracı üzerinden bir komut ekleyelim.
$ cobra-cli add alt
alt created at /xxxxxxxxx/cobra-cli-example
cmd içerisindeki alt.go dosyasında yapmamız gereken tek şey hangi komuta alt komut olarak vereceğimizi belirtmektir. Varsayılan olarak eklenen tüm komutlar rootCmd'ye eklenir. İstersek bu komutu gopher komutuna alt komut olarak ekleyebiliriz. Bunun için alt.go dosyasındaki init() fonksiyonuna bakabiliriz.
cmd/alt.go
rootCmd.AddCommand(altCmd) 
Bu bölümü aşağıdaki gibi değiştirelim.
cmd/alt.go
gopherCmd.AddCommand(altCmd)
Bu değişiklikleri gözlemlemek için aşağıdaki komutu deneyebiliriz.
$ go run . gopher alt 
alt called
Argümanları okuma
Argümanlar komutların yanına girilen, string olarak okunabilen değerlerdir.
Argümanları okuyabilmek için kullanacağımız komutun bir alt-komutu olmaması gerekir.
Örnek olarak root komut üzerinden bir argüman okuyalım.
cmd/root.go
func rootRun(cmd *cobra.Command, args []string) {
	fmt.Println("Merhaba", args[0], "!")
}
Bu yapıya göre aşağıdak şekilde uygulamamızı deneyelim.
$ go run . Kaan
Merhaba Kaan !
Eğer root komutuna bir alt-komut ekli olsaydı, Kaan isimli bir komutun olmadığını gösteren bir hata alacaktık.
$ go run . Kaan 
Error: unknown command "Kaan" for "cobra-cli-example"
Run 'cobra-cli-example --help' for usage.
exit status 1
Bu yüzden argümanlarımızı sadece alt-komut içermeyen komutlar üzerinden okumalıyız.
Bir flag ekleyelim
Flag'leri kullanarak cli uygulamamızı kullanan kullanıcılara seçenekler sunabiliriz. Bir flag eklemek için birden fazla yöntem vardır. İlke olarak flag'imizde ayarlanacak değeri kaydetmek için bir değişken oluşturalım ve aşağıdaki gibi bir yapı kuralım. Bu flag'imizi root komutuna ekleyeceğiz.
Diğer alanlar üzerinden de kullanabilmemiz için değişkenimizi global olarak tanımlayalım.
cmd/root.go
var isim string
Flag'i eklemek için root.go içerisinde init() fonksiyonuna ekleme yapalım.
cmd/root.go
func init() {
	rootCmd.Flags().StringVarP(&isim, "isim", "i", "Ahmet", "--isim <ahmet> veya -i <ahmet>")
}
StringVarP() fonksiyonu ile pointer kullanarak oluşturduğumuz değişkenin adresine komut satırından aldığımız değeri atayabiliriz. Bu flag'i aşağıdaki gibi kullanabiliriz.
rootCmd'nin Run alanına bağladığımız fonksiyon içerisinde kullanalım.
cmd/root.go
func rootRun(cmd *cobra.Command, args []string) {
	fmt.Println("Merhaba",isim,"!")
}
Aşağıdaki komut ile uygulamamızı deneyebiliriz.
$ go run . --isim Kaan
Merhaba Kaan !
Yukarıdakinden farklı olarak başka kullanım şekilleri de vardır.
go run . -i Kaan
go run . --isim=Kaan
go run . --i=Kaan
Aslında gördüğünüz gibi tamamen posix bir cli uygulaması olarak çalışıyor.
Eğer isim flag'ini belirtmeden başlatılırsa varsayılan değer olarak verdiğimiz "Ahmet" kullanılacaktır.
Flag'i ekledikten sonra yardım komutunu çalıştırdığımızda aşağıdaki gibi bir çıktı alırız.
 $ go run . --help
uygulamanın uzun bilgilendirme metnini bu kısma girebilirsiniz.
​
Usage:
  cobra-cli-example [flags]
  cobra-cli-example [command]
​
Available Commands:
  completion  Generate the autocompletion script for the specified shell
  gopher      gopher komutu için kısa tanımlama
  help        Help about any command
​
Flags:
  -h, --help          help for cobra-cli-example
  -i, --isim string   --isim <ahmet> veya -i <ahmet> (default "Ahmet")
​
Use "cobra-cli-example [command] --help" for more information about a command.
Yukarıda gördüğümüz gibi her komut veya flag eklediğimizde bilgilendirmesi yardım alanında görünür.
Eğer kullanacağımız flag sadece uzun flag kullanımı içerecekse StringVar() fonksiyonunu kullanabiliriz.
rootCmd.Flags().StringVar(&isim,"isim","Ahmet","--isim <ahmet> veya -i <ahmet>")
Eğer flag'in bir değer dönmesini istersek, yani işaretçisiz kullanımı için, String() fonksiyonunu kullanabiliriz.
isim := rootCmd.Flags().String("isim", "Ahmet", "--isim <ahmet> veya -i <ahmet>")
Değer dönme ile beraber uzun flag ile kullanmak istersek, StringP() fonksiyonunu kullanabiliriz.
isim := rootCmd.Flags().StringP("isim", "i", "Ahmet", "--isim <ahmet> veya -i <ahmet>")
Yukarıda gördüğümüz yöntemler ile daha farklı veri tipleri için kullanım senaryoları oluşturabiliriz.
Sadece fonksiyon ismindeki String yerine kullanmak istediğiniz veri tipini yazmanız yeterlidir.
Kalıcı (Persistent) flag ekleme
Kalıcı flag'ler üst komutlara eklendiğinde alt komutlar üzerinde de kullanılabilir.
Aşağıdaki örnekte kalıcı flag'imizi root komuta ekleyip gopher komut üzerinde de kullanmayı göreceğiz.
cmd/root.go
rootCmd.PersistentFlags().StringVarP(&isim, "isim", "i", "Ahmet", "--isim <ahmet> veya -i <ahmet>")
Yukarıdaki örnekte flag'in alt komutlar üzerinde de çalışması için, diğer örneklerin aksine Flags() yerine PersistentFlags() fonksiyonunu kullandık. Uygulamamızı deneyelim.
$ go run . gopher -i Kaan 
gopher komutu çalıştı
Böylelikle isim flag'inden gelen değeri de okuyabildik. Bu yöntem dışında yapıldığında, flag'in geçersiz olduğuna dair hata verecektir.
Flag'i zorunlu kılma
Bir komut altındaki bir flag'i zorunlu kılmak için MarkFlagRequired() fonksiyonunu kullanabiliriz.
root.go
rootCmd.Flags().StringVar(&isim, "isim", "Ahmet", "--isim <ahmet> veya -i <ahmet>")
err := rootCmd.MarkFlagRequired("isim")
if err != nil {
    log.Fatalln(err)
}
Uygulamamızı isim flag'ini girmeden başlattığımızda aşağıdaki gibi bir hata alacağız.
$ go run .
Error: required flag(s) "isim" not set
Versiyon belirtme
Uygulamanın --version flag'i ile versiyonunun gösterilmesi için, rootCmd nesnesi tanımlanırken Version alanı içerisine versiyonu bildiren bir numara yazabiliriz. Örnek olarak:
cmd/root.go
1
var rootCmd = &cobra.Command{
2
	Use:     "cobra-cli-example",
3
	Short:   "uygulamanın kısa bilgisi",
4
	Long:    `uygulamanın uzun bilgilendirme metnini bu kısma girebilirsiniz.`,
5
	Run:     rootRun,
6
	Version: "0.1",
7
}
6. satırda uygulamanın versiyonunu belirttik. Uygulama üzerinde deneyelim.
$ go run . --version
cobra-cli-example version 0.1
Kullanımdan kaldırılan (Deprecated) komutlar
Uygulamamızda kullanılan bir alt komutu, yani root olmayan diğer komutları, kaldırmak yerine bu komutların eskide kaldığını kullancılara bildirebiliriz. Bunun için kullanımdan kaldıracağımız komutu aşağıdaki gibi bir ekleme yapabiliriz.
cmd/alt.go
var altCmd = &cobra.Command{
	Use:   "alt",
	Short: "kısa tanım",
	Long:  `uzun tanım`,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("alt çalıştırıldı")
	},
	Deprecated: "[altyeni] komutunu kullanın",
}
Depracated alanına string tipinde bir açıklama yapabiliriz. Deprecated komutlar çalışmaya devam eder. Uygulamamızı deneyelim.
$ go run . alt
Command "alt" is deprecated, [altyeni] komutunu kullanın
alt çalıştırıldı