Claude Code CLI Kullanımı: Print Mode ve Otomasyon Rehberi

Önceki yazıda Claude Code'un kurulumunu ve interaktif oturumda temel kullanımını anlatmıştım. Bu yazıda bir adım öteye geçiyorum: Claude Code'u script'lerden, CI/CD hatlarından ve build araçlarından nasıl çağırırsınız, çıktısını nasıl işlersiniz, oturumları nasıl yönetirsiniz ve izin modlarıyla otomasyonu nasıl güvenli tutarsınız? Tüm örnekler resmi CLI referansı ve headless mod dokümantasyonu üzerinden doğrulanmıştır.

1. İnteraktif Mod ile Print Mode Arasındaki Fark

Terminalde yalnızca claude yazdığınızda interaktif bir oturum açılır: sohbet eder, sorular sorar, izin ister. Ama bir script içinde, bir package.json komutunda ya da bir GitHub Actions adımında Claude'u çağırmak istediğinizde interaktif oturum işinize yaramaz — kimse orada oturup onay vermeyecektir. Bunun için print mode (-p ya da --print) kullanılır: Claude prompt'u işler, sonucu yazdırır ve çıkar.

claude -p "Bu projede auth modülü ne yapıyor?"

Tüm CLI bayrakları -p ile birlikte çalışır; bu yazının geri kalanı büyük ölçüde print mode üzerine kuruludur.

2. Hızlı Başlangıç: --bare Modu

--bare bayrağı, hook'ların, skill'lerin, plugin'lerin, MCP sunucularının, otomatik hafızanın ve CLAUDE.md'nin otomatik keşfini atlayarak başlangıç süresini kısaltır. Bare mod olmadan claude -p, interaktif bir oturumun yükleyeceği tüm bağlamı (çalışma dizininde veya ~/.claude içinde yapılandırılmış her şey dahil) yükler.

claude --bare -p "Bu dosyayı özetle" --allowedTools "Read"

Bare mod, CI ve script'ler için önerilen moddur: bir takım arkadaşının ~/.claude dizinindeki bir hook ya da projenin .mcp.json dosyasındaki bir MCP sunucusu çalışmaz, çünkü bare mod bunları hiç okumaz. Yalnızca açıkça verdiğiniz bayraklar etkili olur. Resmi dokümantasyona göre bare mod OAuth ve keychain okumalarını da atlar; Anthropic kimlik doğrulaması bu durumda ANTHROPIC_API_KEY ortam değişkeninden ya da --settings ile verilen bir apiKeyHelper'dan gelmelidir.

3. Veri Aktarma: stdin'den Piping

Print mode stdin'i okur, bu yüzden veriyi başka bir komuttan pipe ile Claude'a aktarabilir, çıktısını da başka bir dosyaya yönlendirebilirsiniz — tıpkı standart bir Unix aracı gibi:

cat build-error.txt | claude -p 'bu build hatasının kök nedenini kısaca açıkla' > output.txt

Önemli sınır: Claude Code v2.1.128 itibarıyla pipe edilen stdin 10MB ile sınırlıdır. Bu sınır aşılırsa Claude Code net bir hata mesajıyla ve sıfırdan farklı bir çıkış koduyla sonlanır. Daha büyük girdiler için içeriği bir dosyaya yazıp prompt içinde dosya yolunu referans göstermek gerekir.

4. Çıktı Formatları: --output-format

Script'lerin çıktıyı ayrıştırabilmesi için üç format desteklenir:

• text (varsayılan) — düz metin çıktısı.
• json — sonucu, oturum kimliğini ve metadata'yı içeren yapılandırılmış JSON.
• stream-json — gerçek zamanlı akış için satır bazlı (newline-delimited) JSON.

claude -p "Bu projeyi özetle" --output-format json

--output-format json kullanıldığında yanıt gövdesi total_cost_usd ve model bazlı maliyet dökümünü de içerir; bu sayede script'ler kullanım panosuna bakmadan her çağrının maliyetini takip edebilir. Çıktıyı ayrıştırmak için jq kullanmak pratiktir:

# Metin sonucunu çıkar
claude -p "Bu projeyi özetle" --output-format json | jq -r '.result'

Şemaya bağlı yapılandırılmış çıktı

Belirli bir JSON şemasına uyan çıktı almak için --output-format json ile --json-schema'yı birlikte kullanın. Yanıt, yapılandırılmış çıktıyı structured_output alanında taşır:

claude -p "auth.py dosyasındaki ana fonksiyon isimlerini çıkar" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Şema geçersizse claude, Error: --json-schema is not a valid JSON Schema hatasıyla ve doğrulayıcının teşhisiyle birlikte sonlanır.

Akış (stream) yanıtları

Token'ları üretildikçe almak için --output-format stream-json'ı --verbose ve --include-partial-messages ile birlikte kullanın. Akıştaki her satır bir olayı temsil eden JSON nesnesidir, son satır ise nihai yanıt metnini, maliyeti ve oturum bilgisini taşıyan bir result mesajıdır:

claude -p "Özyinelemeyi (recursion) açıkla" --output-format stream-json --verbose --include-partial-messages

5. Oturum Yönetimi: --continue ve --resume

En son konuşmayı sürdürmek için --continue kullanın. Belirli bir konuşmaya dönmek içinse bir oturum kimliğiyle birlikte --resume kullanılır:

# İlk istek
claude -p "Bu kod tabanını performans sorunları için incele"

# En son konuşmayı sürdür
claude -p "Şimdi veritabanı sorgularına odaklan" --continue
claude -p "Bulunan tüm sorunların özetini çıkar" --continue

Paralel birden fazla konuşma yürütüyorsanız oturum kimliğini yakalayıp belirli birine dönebilirsiniz:

session_id=$(claude -p "İncelemeye başla" --output-format json | jq -r '.session_id')
claude -p "O incelemeye devam et" --resume "$session_id"

Oturum kimliği araması çalışma dizinine ve onun git worktree'lerine göre sınırlıdır; bu yüzden her iki komutu da aynı dizinden çalıştırmanız gerekir.

6. İzin Modları (Permission Modes)

Otomasyonda en kritik konu izinlerdir: Claude'un hangi işlemleri sormadan yapabileceğini izin modu belirler. Aşağıdaki tablo her modun sormadan neyi çalıştırdığını özetler:

Mod	Sormadan çalışan	En uygun kullanım
default (Manual)	Yalnızca okuma işlemleri	Başlangıç, hassas işler
plan	Yalnızca okuma işlemleri	Değişiklik öncesi kod tabanını keşfetmek
acceptEdits	Okuma, dosya düzenleme ve mkdir/touch/mv/cp gibi yaygın dosya sistemi komutları	İnceleyeceğiniz kod üzerinde yineleme yapmak
dontAsk	Yalnızca önceden onaylanmış (permissions.allow) araçlar	Kilitli CI hatları ve script'ler
bypassPermissions	Her şey, hiçbir kontrol olmadan	Yalnızca izole container/VM

Bir modu oturum başında ayarlamak için:

claude -p "Lint düzeltmelerini uygula" --permission-mode acceptEdits

CI için önerilen mod dontAsk'tır: Claude yalnızca permissions.allow kurallarınıza, salt okunur komut kümesine ve bir PreToolUse hook'unun onayladığı çağrılara uyan işlemleri çalıştırır; geri kalan her şey otomatik reddedilir ve oturum girdi beklemeden ilerler.

claude -p "Test paketini çalıştır ve başarısız olanları raporla" --permission-mode dontAsk \
  --allowedTools "Bash(npm test)"

bypassPermissions (ya da eşdeğeri --dangerously-skip-permissions) tüm izin kontrollerini ve güvenlik denetimlerini devre dışı bırakır; yalnızca internet erişimi olmayan izole container veya sanal makineler gibi ortamlarda kullanılmalıdır.

--allowedTools ve izin kuralı sözdizimi

--allowedTools, Claude'un belirli araçları sormadan kullanmasına izin verir. Bu örnek, Claude'a test paketini çalıştırıp hataları düzeltirken Bash komutu çalıştırma ve dosya okuma/düzenleme izni verir:

claude -p "Test paketini çalıştır ve başarısız olanları düzelt" \
  --allowedTools "Bash,Read,Edit"

Belirli komut kalıplarını hedeflemek için parantez içi sözdizimi kullanılır; sondaki boşluk + * önek eşleşmesini (prefix matching) etkinleştirir:

claude -p "Stage edilmiş değişiklikleri incele ve uygun bir commit oluştur" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

*'dan önceki boşluk önemlidir: onsuz Bash(git diff*), git diff-index gibi ilgisiz komutları da eşleştirebilir. Belirli araçları engellemek için ise --disallowedTools aynı sözdizimini kullanır.

7. Sistem Promptunu Özelleştirme

Varsayılan davranışı korurken talimat eklemek için --append-system-prompt kullanılır. Bu örnek bir PR diff'ini Claude'a aktarıp güvenlik açıkları için incelemesini ister:

gh pr diff "$1" | claude -p \
  --append-system-prompt "Sen bir güvenlik mühendisisin. Güvenlik açıkları için incele." \
  --output-format json

Varsayılan sistem promptunu tamamen değiştirmek isterseniz --system-prompt (veya dosyadan yüklemek için --system-prompt-file) kullanılabilir.

8. Gerçek Dünya Örneği: Build Script'ine Claude Ekleme

Print mode'u proje özelinde bir linter ya da reviewer olarak bir script içine sarabilirsiniz. Aşağıdaki package.json script'i, main dalına göre diff'i Claude'a pipe eder ve yazım hatalarını raporlamasını ister. Diff'i pipe etmek, Claude'un onu okumak için Bash iznine ihtiyaç duymamasını sağlar; kaçış karakterli çift tırnaklar da script'i Windows'a taşınabilir kılar:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"sen bir yazim hatasi denetleyicisisin. bu diff'teki her yazim hatasi icin dosyaadi:satir bir satirda, sorunu bir sonraki satirda raporla. baska bir sey donme.\""
  }
}

CI ve diğer script tabanlı çağrılar için yerel yapılandırmayı (hook, MCP sunucusu vb.) yanlışlıkla yüklememek adına --bare eklemek her makinede aynı sonucu almanızı sağlar:

cat build-error.txt | claude --bare -p 'bu build hatasının kök nedenini kısaca açıkla' --allowedTools "Read"

9. Verimli Otomasyon İçin İpuçları

• CI'da her zaman --bare kullanın. Aksi halde bir hook ya da MCP sunucusu, çalıştırdığınız makineye göre farklı sonuçlar üretebilir.
• İzinleri en dar kapsamda tanımlayın. Bash(*) gibi geniş kurallar yerine Bash(npm test) gibi belirli komutlar kullanın.
• Maliyeti --output-format json ile takip edin. total_cost_usd alanı, script bazlı harcamayı panele bakmadan görmenizi sağlar.
• --max-turns gibi sınırları unutmayın. Otomatik çağrılarda kontrolsüz uzun döngüleri önlemek için tur sayısını sınırlamak faydalıdır.
• Session ID'yi loglayın. Paralel çalışan otomasyon adımlarında hangi oturumun hangi işi yaptığını izlemek, hata ayıklamayı kolaylaştırır.

Sıkça Sorulan Sorular

Claude Code'da print mode (-p) ne işe yarar?

-p (ya da --print) bayrağı, Claude Code'u interaktif bir sohbet açmadan tek seferlik çalıştırır: prompt'u işler, sonucu yazdırır ve çıkar. Script'lerde, CI adımlarında ve build araçlarında kullanmak için tasarlanmıştır; tüm CLI bayrakları -p ile birlikte çalışır.

-c (--continue) ile -r (--resume) arasındaki fark nedir?

--continue geçerli klasördeki en son konuşmayı otomatik olarak sürdürür. --resume ise belirli bir session ID vererek o oturuma dönmenizi sağlar; birden fazla paralel konuşma yürütüyorsanız session_id'yi --output-format json çıktısından yakalayıp --resume ile hedeflemeniz gerekir.

CI ortamında hangi izin modu kullanılmalı?

Kilitli CI hatları için dontAsk modu önerilir: yalnızca permissions.allow kurallarınıza ve salt okunur komut kümesine uyan işlemler çalışır, geri kalan her şey otomatik reddedilir ve oturum kullanıcı beklemeden ilerler. --allowedTools ile hangi araçlara izin verildiğini açıkça listelemek en güvenli yaklaşımdır.

--dangerously-skip-permissions ne zaman kullanılmalı?

Bu bayrak bypassPermissions moduna eşdeğerdir ve tüm izin kontrollerini devre dışı bırakır. Yalnızca internet erişimi olmayan, izole container veya sanal makineler gibi ortamlarda kullanılmalıdır; ana makinenizde veya paylaşılan bir sistemde asla kullanılmamalıdır.

Piped girdi (stdin) için bir boyut sınırı var mı?

Evet. Claude Code v2.1.128 itibarıyla stdin üzerinden aktarılan veri 10MB ile sınırlıdır; bu sınır aşılırsa Claude Code hata verip sıfırdan farklı bir çıkış koduyla sonlanır. Daha büyük girdiler için içeriği bir dosyaya yazıp prompt içinde dosya yolunu referans göstermek gerekir.

Özet

Claude Code'u otomasyona bağlamanın anahtarı print mode'dur (-p): interaktif oturumdaki tüm yeteneklere script'ten erişebilirsiniz. Pratik bir kural seti şöyle özetlenebilir: script ve CI çağrılarında --bare ile başlayın, çıktıyı --output-format json veya stream-json ile yapılandırılmış alın, birden fazla adımı --continue/--resume ile bağlayın, ve izinleri dontAsk + dar kapsamlı --allowedTools kurallarıyla kilitleyin. bypassPermissions'ı yalnızca izole ortamlarda kullanın. Bu temel üzerine, bir sonraki adım olarak /init ile oluşturduğunuz CLAUDE.md dosyasını script'lerinize göre nasıl yapılandıracağınıza bakmak mantıklı olacaktır — kurulum yazısında değindiğim temel komutlar bu noktada hâlâ geçerlidir.

İlgili araç: Script ve CI kullanımının API maliyetini önden kestirmek için LLM Token & Maliyet Hesaplayıcı'ya bakabilirsiniz — istek sayısı ve önbellek oranıyla birlikte toplam maliyeti hesaplar.