Comment on page
🐍
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
vecobra add cmdname
gibi komutlarla kolayca yapı oluşturma,- Akıllı öneriler (
app servr
... did you meanapp 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
go get -u github.com/spf13/cobra@latest
go install github.com/spf13/cobra@latest
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ı
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.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ı
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 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.
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ı 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.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
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
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ı