← blog · 17 Kasım 2026

Betiklere Dost CLI Aracı Yazmak: Çıkış Kodları, stdout ile stderr Ayrımı, JSON Çıktı, TTY Algılama ve Sinyaller

Elle denendiğinde kusursuz çalışan bir komut satırı aracı boru hattına girince neden sessizce yanlış sonuç üretir? Çıkış kodu, stdout ile stderr ayrımı, makine okunur çıktı, terminal algılama, sinyaller ve kırık boru için uygulanabilir kurallar ve Go örnekleri.

Bir komut satırı aracı iki tür kullanıcıya hizmet eder: terminalde elle çalıştıran insana ve onu bir betiğin, CI adımının ya da başka bir programın içinden çağıran makineye. İnsan için yazılmış araçlar genelde ikinci kullanıcıyı unutur. Hata olduğunda sıfır döner, ilerleme çubuğunu dosyaya yönlendirilmiş çıktının içine basar, renk kodlarıyla JSON'u bozar, Ctrl-C'de yarım dosya bırakır. Sonuç tanıdıktır: araç elle denendiğinde kusursuzdur, bir boru hattına girdiği anda sessizce yanlış sonuç üretir. Bu yazıda bir CLI aracını betiklere dost yapan sözleşmeyi ve Go'da bunun nasıl kurulacağını anlatıyoruz.

Sözleşmenin dört parçası

Bir CLI aracının dış dünyayla sözleşmesi dört kanaldan oluşur: çıkış kodu, standart çıktı, standart hata ve sinyaller. Betik yazan biri bu dördüne güvenebiliyorsa aracınız otomasyona girer; birine güvenemiyorsa etrafına sarmalayıcı yazar ve sonunda başka bir araç bulur.

Çıkış kodu: tek güvenilir sinyal

Kabuk, set -e, CI sistemleri ve süreç yöneticileri yalnızca çıkış koduna bakar. Hata mesajını okuyan yoktur. Bu yüzden ilk kural basittir: başarısız olan her yol sıfırdan farklı bir kodla çıkar.

Kod seçerken kullanışlı bir ayrım şudur:

  • 0 başarı.
  • 1 genel hata: işlem denendi ve başarısız oldu.
  • 2 kullanım hatası: yanlış bayrak, eksik argüman. Go'nun standart flag paketi de ayrıştırma hatasında bu kodla çıkar, yani bu bir gelenektir.
  • 130 Ctrl-C ile kesilme. Kabuk geleneği 128 artı sinyal numarasıdır, SIGINT 2 olduğu için 130 olur.

Bunların ötesinde koda anlam yüklemek isterseniz (örneğin "değişiklik yok" için ayrı bir kod) bunu belgeleyin ve bir daha değiştirmeyin. grep eşleşme yoksa 1, hata varsa 2 döner ve bu ayrım yıllardır betiklerin dayandığı bir sözleşmedir.

Go'da sık düşülen tuzak os.Exit'tir. os.Exit ertelenmiş (defer) fonksiyonları çalıştırmaz. main içinde dosya kapatan, geçici dizin silen ya da tampon boşaltan bir defer yazıp ardından bir hata yolunda os.Exit(1) çağırırsanız temizlik hiç yapılmaz. log.Fatal de aynı şeyi içeride yapar. Doğru desen, bütün işi hata döndüren bir fonksiyona taşımak ve çıkışı tek bir yerde yapmaktır:

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	context.AfterFunc(ctx, stop)
	err := run(ctx, os.Args[1:], os.Stdout, os.Stderr)
	interrupted := ctx.Err() != nil
	stop()
	os.Exit(exitCode(err, interrupted))
}

func exitCode(err error, interrupted bool) int {
	var uerr *usageError
	switch {
	case err == nil:
		return 0
	case errors.As(err, &uerr):
		return 2
	case interrupted:
		return 130
	default:
		return 1
	}
}

run içindeki her defer artık run dönerken çalışır, çıkış ise sonradan gelir. Kesilme bilgisinin stop() çağrısından önce okunduğuna dikkat edin: stop bağlamı da iptal eder, sonradan bakarsanız her hata 130 gibi görünür. usageError sizin tanımlayacağınız basit bir hata türüdür. Bu desenin ikinci kazancı test edilebilirliktir: run fonksiyonuna argüman ve yazıcı verip çıktıyı ve hatayı doğrudan test edebilirsiniz, alt süreç başlatmanıza gerek kalmaz.

stdout veri içindir, stderr insan içindir

Kural şu: standart çıktıya yalnızca aracın ürettiği veri yazılır. İlerleme bilgisi, uyarılar, "3 dosya işlendi" gibi özetler ve hata mesajları standart hataya gider. Bu ayrımın sebebi yönlendirmedir. arac liste > sonuc.txt ya da arac liste | jq çalıştıran biri dosyaya ya da boruya yalnızca veriyi ister, ilerleme mesajlarını ise yine terminalde görmek ister. İkisini aynı kanala yazarsanız ya veri bozulur ya da kullanıcı ne olduğunu göremez.

Bunu yapmanın en sağlam yolu, yukarıdaki örnekteki gibi run fonksiyonuna iki ayrı io.Writer vermektir. Kod içinde doğrudan fmt.Println kullanmak yerine verilen yazıcıya yazmak, yanlış kanala yazmayı zorlaştırır ve testte iki kanalı ayrı ayrı yakalamanızı sağlar.

Bir uyarı daha: standart çıktıyı tamponluyorsanız (bufio.Writer), çıkıştan önce Flush çağırmayı ve dönen hatayı kontrol etmeyi unutmayın. Disk dolduğunda ya da boru kapandığında yazma hatası tam bu noktada ortaya çıkar; hatayı görmezden gelirseniz araç eksik çıktı üretip sıfırla çıkar.

Makine okunur çıktı ayrı bir arayüzdür

İnsan için hizalanmış tablo güzeldir ama betik onu awk ile ayrıştırmaya çalıştığında her sütun genişliği değişikliği bir şeyi kırar. Çözüm, ikinci bir çıktı biçimi sunmaktır: --json ya da --output json. Burada taraf tutalım: sütunlu düz metni "makine okunur" diye sunmak yerine gerçek JSON verin. JSON alan eklemeye dayanıklıdır, yeni bir alan eski ayrıştırıcıları kırmaz; boşluklu değerler, yeni satırlar ve Unicode sorun çıkarmaz.

JSON çıktısının da bir sözleşme olduğunu unutmayın:

  • Alan adlarını ve türlerini kararlı tutun; insan tablosundaki başlıkları değiştirmek serbesttir, JSON alanını yeniden adlandırmak kırıcı değişikliktir.
  • Uzun listeler için satır başına bir JSON nesnesi (JSON Lines) düşünün. Tüketici akışı satır satır işleyebilir, siz de tüm sonucu bellekte toplamak zorunda kalmazsınız.
  • Hata durumunda da standart çıktıya yarım bir JSON belgesi bırakmayın. Ya geçerli bir belge yazın ya da hiçbir şey yazmayın; hatanın kendisi standart hataya ve çıkış koduna gider.

Terminal mi, boru mu?

Renk, ilerleme çubuğu, etkileşimli onay sorusu ve sayfalayıcı yalnızca karşıda bir insan varsa anlamlıdır. Bunu anlamanın yolu çıktının bir terminale bağlı olup olmadığına bakmaktır. Go'da golang.org/x/term paketindeki term.IsTerminal(int(os.Stdout.Fd())) bunu söyler.

Uygulanacak kurallar:

  • Renk yalnızca hedef kanal bir terminalse açılsın. Renk kararını stdout ve stderr için ayrı verin; arac 2>hata.log çalıştırıldığında stdout hâlâ terminal olabilir.
  • NO_COLOR ortam değişkeni tanımlı ve boş değilse renk kapansın. Bu yaygın kabul görmüş bir gelenektir; bir de --color=always|never|auto bayrağı sunun ki CI günlüğünde renk isteyen açabilsin.
  • Onay sorusu soracaksanız standart girdinin terminal olduğunu kontrol edin. Terminal değilse soru sormak yerine hata verip --yes gibi açık bir bayrak isteyin. Aksi hâlde araç CI'da sonsuza kadar girdi bekler ya da boş girdiyi "evet" sayar.
  • İlerleme çubuğunu stderr'e yazın ve stderr terminal değilse hiç çizmeyin. Satır başı karakterleriyle dolmuş bir CI günlüğü okunmaz.

Sinyaller ve yarım iş

Ctrl-C bastığınızda terminal SIGINT gönderir; konteyner ve süreç yöneticileri durdururken SIGTERM gönderir. Go'da varsayılan davranış süreci hemen öldürmektir ve defer'lar çalışmaz. Yukarıdaki signal.NotifyContext bu sinyalleri bir context iptaline çevirir. Uzun süren her işlem bu context'i almalı ve iptal edildiğinde temiz biçimde dönmelidir: ağ istekleri http.NewRequestWithContext ile, döngüler her adımda ctx.Err() kontrolüyle.

Yarım dosya sorununu çözmenin yolu atomik yazmadır: çıktıyı hedefle aynı dizinde geçici bir dosyaya yazın, Sync ile diske indirin, kapatın ve ancak her şey başarılıysa os.Rename ile hedefin üzerine taşıyın. Aynı dosya sistemi içinde yeniden adlandırma ya tamamen olur ya hiç olmaz; kesilen bir çalıştırma eski dosyayı sağlam bırakır. Geçici dosyayı os.TempDir altında açarsanız hedef başka bir dosya sistemindeyse yeniden adlandırma başarısız olur, bu yüzden aynı dizin önemlidir.

İkinci Ctrl-C'yi de düşünün. Temizlik uzun sürüyorsa kullanıcı tekrar basar. NotifyContext'in döndürdüğü stop çağrıldıktan sonra sinyal varsayılan davranışına döner. Örnekteki context.AfterFunc(ctx, stop) satırı (Go 1.21 ve sonrası) bunu ilk sinyalde yapar: ilk basış nazik bir kapanış başlatır, ikinci basış süreci hemen sonlandırır. Kullanıcının beklediği de budur; bu satır olmazsa takılan bir temizlik adımında araç Ctrl-C'yi yutar ve tek çare kill -9 kalır.

Kırık boru

arac liste | head -n 5 çalıştırıldığında head beş satırdan sonra kapanır ve aracınız kapalı bir boruya yazmaya çalışır. Go çalışma zamanı, program SIGPIPE için kendi işleyicisini kurmadıysa, standart çıktı ya da standart hataya yapılan böyle bir yazmada süreci SIGPIPE ile sonlandırır. Bu çoğu zaman doğru davranıştır ve kabuk bunu hata saymaz. Sorun, SIGPIPE'ı da signal.Notify ile yakalayan ya da tüm sinyalleri dinleyen kodda çıkar: artık yazma hatası EPIPE olarak döner ve araç bunu genel bir hata gibi raporlayıp 1 ile çıkar, set -o pipefail açık betikler de boşuna düşer. Bilinçli bir gerekçeniz yoksa SIGPIPE'ı yakalamayın; yakalıyorsanız syscall.EPIPE hatasını sessiz bir çıkış olarak ele alın.

Ne zaman bunlarla uğraşmamalı

Yalnızca sizin çalıştırdığınız, bir kez kullanılıp atılacak bir yardımcı için bu disiplinin çoğu gereksizdir; doğru çıkış kodu yine de şarttır, çünkü bir gün birisi onu bir betiğe koyacaktır. Aracınız tamamen etkileşimli bir arayüzse (tam ekran terminal uygulaması) makine okunur çıktı yerine aynı işi yapan ayrı, etkileşimsiz alt komutlar sunmak daha temiz olur. Bir de çok fazla çıktı biçimi eklemeyin: insan için metin ve makine için JSON çoğu aracın ihtiyacını karşılar, YAML, CSV ve şablon desteği her biri ayrıca bakım ve test yükü getirir.

Kontrol listesi

Aracınızı yayınlamadan önce şu komutları deneyin: arac yanlis-bayrak; echo $? iki vermeli. arac liste > /dev/null terminalde ilerleme ve uyarıları göstermeli. arac liste --json | jq . hatasız ayrışmalı. arac liste | head -n 1 hata mesajı basmadan bitmeli. NO_COLOR=1 arac liste renksiz olmalı. Uzun bir işlemin ortasında Ctrl-C hedef dosyayı bozmamalı ve 130 ile çıkmalı. Bu altı denemeyi geçen bir araç, onu kullanan betiklerin sessizce yanlış sonuç üretmesine yol açmaz.