Gemini CLI Rehberi: Kurulum, GEMINI.md, MCP, Headless Mod ve Claude Code Karşılaştırması

Terminalde çalışan yapay zekâ kodlama ajanları artık geliştirici araç kutusunun sabit bir parçası. Bu alanda Anthropic'in Claude Code'u kadar sık karşılaşılan bir diğer isim de Google'ın açık kaynaklı Gemini CLI'ı. Bu rehberde Gemini CLI'ı yalnızca Google'ın kendi resmi kaynaklarına — github.com/google-gemini/gemini-cli deposundaki README, docs/ klasörü ve sürüm notlarına — dayanarak uçtan uca anlatıyoruz: kurulum ve kimlik doğrulama, kota ve ücretlendirme mantığı, GEMINI.md bağlam dosyaları, onay modları ve Plan Mode, özel komutlar, MCP sunucuları, hook'lar, sandbox, headless (betik) modu ve son olarak Claude Code ile pratik bir karşılaştırma. Yazının sonunda iki aracı aynı repoda birlikte kullanmak isteyenler için ortak bir AGENTS.md stratejisi de bulacaksınız.

Not: Gemini CLI çok hızlı gelişen bir proje; her hafta yeni preview ve stable sürümler çıkıyor. Bu yazıdaki bilgiler 8 Ekim 2026 itibarıyla depodaki main dalı dokümantasyonuna ve o tarihteki son stable sürüm olan v0.63.0'a göre derlenmiştir. Komut ve ayar adlarını kendi kurulumunuzda gemini --help ile doğrulamanız iyi bir alışkanlık olur.

Gemini CLI Nedir?

Resmi README'nin tanımıyla Gemini CLI, "Gemini'nin gücünü doğrudan terminalinize getiren açık kaynaklı bir yapay zekâ ajanıdır". Proje Apache 2.0 lisanslıdır; yani kaynak kodunu okuyabilir, fork'layabilir ve kendi ihtiyaçlarınıza göre değiştirebilirsiniz. README'de öne çıkarılan başlıklar şunlar:

• Ücretsiz kullanım katmanı: Kişisel Google hesabıyla giriş yapıldığında dakikada 60 istek ve günde 1.000 istek.
• Gemini 3 modelleri: Geliştirilmiş akıl yürütme ve 1M token'lık bağlam penceresi.
• Yerleşik araçlar: Google Search ile grounding, dosya işlemleri, shell komutları ve web'den içerik çekme (web fetch).
• Genişletilebilirlik: MCP (Model Context Protocol) desteği, eklentiler (extensions), özel komutlar ve agent skills.
• Terminal öncelikli tasarım: Komut satırında yaşayan geliştiriciler için.

Kısacası Gemini CLI, Claude Code ile aynı kategoride yer alan bir "agentic" kodlama aracıdır: kod tabanınızı okur, dosya düzenler, komut çalıştırır, araç çağırır ve bunları sizin onay politikalarınız çerçevesinde yapar. Farkları ise model ailesinde, ücretlendirme yapısında, yapılandırma formatlarında ve ekosistemde ortaya çıkıyor — bunlara aşağıda ayrıntılı olarak değineceğiz.

Gemini CLI Nasıl Kurulur?

Resmi kurulum dokümanına göre Gemini CLI'ın çalışma zamanı gereksinimi Node.js 20.0.0 veya üzeridir. Kurulum için birkaç seçenek var:

# Kurmadan, anında çalıştırmak için
npx @google/gemini-cli

# npm ile global kurulum
npm install -g @google/gemini-cli

# Homebrew (macOS/Linux)
brew install gemini-cli

# MacPorts (macOS)
sudo port install gemini-cli

Kurulumu doğrulamak için gemini --version, güncellemek için ise gemini update komutunu kullanabilirsiniz.

Sürüm kanalları: stable, preview ve nightly

Gemini CLI'ın yayın takvimi oldukça düzenlidir ve bunu bilmek, ekip içinde sürüm sabitlemek açısından önemlidir:

Kanal	Ne zaman yayınlanır?	Kurulum
Stable (latest)	Her salı UTC 20:00; bir önceki haftanın preview sürümü + hata düzeltmeleri	npm install -g @google/gemini-cli@latest
Preview	Her salı UTC 23:59; tam doğrulanmamış, regresyon içerebilir	npm install -g @google/gemini-cli@preview
Nightly	Her gün UTC 00:00; main dalının o anki hâli	npm install -g @google/gemini-cli@nightly

Üretim işleri ve CI için stable kanal mantıklı tercihtir. 6 Ekim 2026'da yayınlanan v0.63.0'ın öne çıkan değişiklikleri arasında etkileşimsiz (non-interactive) modda otonom plan yürütme, uzun süren ajan döngülerinde araç çıktısı boyutunun sınırlandırılması, dosya çakışması ve headless keyring ortamlarından kaynaklanan sonsuz kimlik doğrulama döngülerinin giderilmesi ve bağlantı kurtarma sırasında yeniden deneme göstergesi yer alıyor.

Kimlik Doğrulama: Google Hesabı, API Anahtarı mı, Vertex AI mı?

Gemini CLI'ı ilk çalıştırdığınızda (gemini) bir kimlik doğrulama yöntemi seçmeniz istenir. README üç ana yol tanımlıyor:

1. Google ile giriş (OAuth)

Bireysel geliştiriciler ve Gemini Code Assist lisansı olanlar için önerilen yol. API anahtarı yönetmeniz gerekmez; tarayıcıda Google hesabınızla oturum açarsınız. Kurumunuzun ücretli Code Assist lisansını kullanıyorsanız Google Cloud projenizi belirtmeniz gerekir:

export GOOGLE_CLOUD_PROJECT="PROJE_KIMLIGINIZ"
gemini

2. Gemini API anahtarı

Belirli bir model üzerinde kontrol isteyen veya kullanım bazlı (pay-as-you-go) faturalandırmaya geçmek isteyen geliştiriciler için. Anahtarı Google AI Studio'dan alıp ortam değişkeni olarak verirsiniz:

export GEMINI_API_KEY="API_ANAHTARINIZ"
gemini

3. Vertex AI

Kurumsal ekipler ve üretim iş yükleri için; Google Cloud altyapısıyla entegrasyon, güvenlik ve uyumluluk özellikleri sunar:

export GOOGLE_API_KEY="API_ANAHTARINIZ"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Gemini CLI Ücretsiz mi? Kotalar ve Ücretlendirme

Türk geliştiriciler için en pratik soru bu: Gemini CLI'ı ücretsiz kullanabilir miyim? Cevap "evet, ama kimlik doğrulama yönteminize göre değişen günlük limitlerle". Depodaki docs/resources/quota-and-pricing.md belgesi kullanıcı başına günlük azami istek sayılarını şöyle listeliyor:

Kimlik doğrulama	Katman / Abonelik	Günlük azami istek (kullanıcı başına)
Google hesabı	Gemini Code Assist (Individual)	1.000
Google hesabı	Google AI Pro	1.500
Google hesabı	Google AI Ultra	2.000
Gemini API anahtarı	Ücretsiz katman	250 (yalnızca Flash modeli)
Gemini API anahtarı	Pay-as-you-go	Değişken
Vertex AI	Express mode (ücretsiz)	Değişken
Google Workspace	Code Assist Standard	1.500
Google Workspace	Code Assist Enterprise / Workspace AI Ultra	2.000

Dikkat edilmesi gereken birkaç ayrıntı:

• Kaynaklar arasında fark var: README, API anahtarıyla ücretsiz katmanı "günde 1.000 istek (Flash ve Pro karışımı)" olarak anarken, ayrıntılı kota belgesi 250 istek ve yalnızca Flash modeli diyor. Gerçek limitinizi her zaman CLI içindeki /stats model komutuyla kontrol edin; bu komut oturumdaki token kullanımınızı ve mevcut kotanıza ait limit bilgilerini gösterir.
• Google ile girişte model seçimi CLI'a aittir: Code Assist for individuals katmanında istekler "Gemini CLI'ın belirlediği şekilde Gemini model ailesine" dağıtılır.
• Vertex AI Express mode faturalandırmayı etkinleştirmeden 90 gün kullanım imkânı tanır; kota ve modeller hesaba göre değişir.
• Desteklenmeyen planlar: Belge, Google AI Plus ile Workspace AI Standard/Plus ve AI Expanded katmanlarının Gemini CLI için desteklenmediğini açıkça belirtiyor.
• Kesintisiz kullanım için pay-as-you-go: Günlük limite takılmak istemiyorsanız belge, API anahtarı veya Vertex AI ile kullanım bazlı ödemeye geçmeyi "kesintisiz erişim için önerilen yol" olarak tanımlıyor. Token başına fiyatlar modele göre değişir; güncel rakamlar için Gemini API'nin resmi fiyatlandırma sayfasına bakmalısınız.

Claude Code tarafında ise resmi kurulum belgesine göre bir Pro, Max, Team, Enterprise veya Console hesabı gerekir; ücretsiz claude.ai planı Claude Code erişimi içermez. Bu, bütçesi kısıtlı öğrenciler ve hobi projeleri için Gemini CLI'ı cazip kılan en somut farktır. Öte yandan ücretsiz katmandaki istek limitleri, uzun ajan döngülerinde (her araç çağrısı bir model isteği demektir) beklenenden hızlı tükenebilir; bu yüzden /stats model çıktısını takip etmek önemlidir.

Model Seçimi: Auto, Pro ve Flash

/model komutu bir diyalog açar ve üç seçenek sunar:

Seçenek	Açıklama	Modeller
Auto (Gemini 3)	Göreve göre en uygun Gemini 3 modelini sistem seçer	gemini-3-pro-preview, gemini-3-flash-preview
Auto (Gemini 2.5)	Göreve göre en uygun Gemini 2.5 modelini sistem seçer	gemini-2.5-pro, gemini-2.5-flash
Manual	Belirli bir modeli elle seçersiniz	Erişilebilen herhangi bir model

Başlangıçta model belirtmek için -m / --model bayrağı kullanılır. CLI referansı şu takma adları (alias) tanımlar: auto (varsayılan; preview özellikleri açıksa gemini-3-pro-preview, değilse gemini-2.5-pro), pro, flash (gemini-2.5-flash) ve flash-lite (gemini-2.5-flash-lite).

gemini -m flash
gemini -m gemini-2.5-flash

Resmi öneri şöyle: çoğu kullanıcı için Auto ile başlayın; sonuçlar yetersizse karmaşık, çok aşamalı hata ayıklama gibi işler için Pro'ya geçin; JSON'u YAML'a çevirmek gibi basit ve hız gerektiren işler için Flash ya da Flash-Lite kullanın. Önemli bir not: /model komutu ve --model bayrağı subagent'ların kullandığı modeli değiştirmez; bu yüzden kullanım raporlarında seçtiğinizden farklı modeller görebilirsiniz.

Claude Code'daki karşılığı, /model komutu ve --model bayrağıyla Opus, Sonnet ve Haiku aileleri arasında seçim yapmaktır; Claude Code ayrıca --effort gibi akıl yürütme derinliği ayarları da sunar. İki araçta da mantık benzer: zor iş için büyük model, rutin iş için hızlı ve ucuz model.

GEMINI.md ile Proje Bağlamı Nasıl Verilir?

Claude Code kullanıcılarının CLAUDE.md'den tanıdığı fikrin Gemini CLI'daki karşılığı GEMINI.md bağlam dosyalarıdır. Her istemde aynı talimatları tekrarlamak yerine kodlama stilinizi, proje mimarisini ve kurallarınızı bir kez yazarsınız. Gemini CLI bu dosyaları hiyerarşik olarak yükler, içeriklerini birleştirir ve her istemle birlikte modele gönderir:

1. Global bağlam: ~/.gemini/GEMINI.md — tüm projeleriniz için varsayılan talimatlar.
2. Ortam ve çalışma alanı bağlamı: Yapılandırılmış çalışma alanı dizinlerinde ve bunların üst dizinlerinde bulunan GEMINI.md dosyaları.
3. Just-in-time (JIT) bağlam: Bir araç bir dosyaya veya dizine eriştiğinde CLI, o dizinde ve güvenilir köke kadar üst dizinlerinde GEMINI.md arar. Böylece belirli bir bileşene özel talimatlar yalnızca gerektiğinde bağlama girer.

Örnek bir proje kökü GEMINI.md dosyası:

# Proje: Fatura Servisi

## Genel Talimatlar
- Yeni TypeScript kodu mevcut stile uymalı.
- Tüm yeni fonksiyon ve sınıflara JSDoc yorumu ekle.

## Kodlama Stili
- Girinti 2 boşluk.
- Her zaman katı eşitlik kullan (=== ve !==).

@./docs/api-kurallari.md

Son satırdaki @./docs/api-kurallari.md, büyük bağlam dosyalarını parçalara bölmenizi sağlayan import sözdizimidir; göreli ve mutlak yollar desteklenir. Yüklenen bağlamı yönetmek için iki komut vardır:

• /memory show — modele gönderilen birleştirilmiş bağlamın tamamını gösterir; "model neden böyle davranıyor?" sorusunun ilk durağıdır.
• /memory reload — tüm GEMINI.md dosyalarını yeniden tarar ve yükler.

CLI'ın alt bilgi satırı (footer) yüklenen bağlam dosyası sayısını gösterir. Ayrıca bağlama girmesini istemediğiniz dosyaları, .gitignore sözdizimini izleyen bir .geminiignore dosyasıyla hariç tutabilirsiniz; değişikliklerin geçerli olması için oturumu yeniden başlatmanız gerekir.

Bağlam dosyasının adını değiştirmek: AGENTS.md ile ortak talimatlar

Gemini CLI'ın az bilinen ama çok kullanışlı bir ayarı context.fileName'dir. Bununla GEMINI.md yerine (veya yanında) başka dosya adlarını bağlam dosyası olarak tanımlayabilirsiniz:

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

Bu, birden fazla kodlama ajanı kullanan ekipler için önemli bir kapı açıyor. Claude Code'un resmi hafıza dokümantasyonuna göre Claude Code da, çalışma dizininde veya üstünde CLAUDE.md / CLAUDE.local.md yoksa repodaki AGENTS.md'yi proje talimatı olarak doğrudan okuyabiliyor (bu davranış Claude Code v2.1.277 ve sonrasını gerektiriyor). Her iki dosya da varsa Claude yalnızca CLAUDE.md dosyalarını okur; bu durumda CLAUDE.md içinden @AGENTS.md şeklinde import yaparak ortak dosyayı dahil edebilirsiniz. Sonuç: tek bir AGENTS.md dosyası hem Gemini CLI hem Claude Code için ortak "proje anayasası" olabilir. Claude Code'daki hafıza sistemini ayrıntılı öğrenmek için Claude Code'da CLAUDE.md ve Auto Memory rehberimize göz atabilirsiniz.

Ayarlar: settings.json Katmanları

Gemini CLI kalıcı yapılandırma için JSON dosyaları kullanır. Öncelik sırası (sonraki öncekini ezer) şöyledir:

1. Uygulamanın içindeki varsayılan değerler
2. Sistem varsayılanları dosyası (Linux'ta /etc/gemini-cli/system-defaults.json)
3. Kullanıcı ayarları: ~/.gemini/settings.json
4. Proje ayarları: .gemini/settings.json
5. Sistem ayarları dosyası (diğer tüm ayar dosyalarını ezer)
6. Ortam değişkenleri (.env dosyalarından da yüklenebilir)
7. Komut satırı argümanları

Bu yapı, Claude Code'un ~/.claude/settings.json (kullanıcı), .claude/settings.json (proje) ve kurumsal managed settings katmanlarına kavramsal olarak çok benzer. Fark, dizin adında (.gemini/ ve .claude/) ve alan adlarındadır; bir aracın ayar dosyasını diğerine kopyalayamazsınız. Depo, JSON destekli editörlerde otomatik tamamlama için schemas/settings.schema.json şemasını da yayınlıyor.

Onay Modları ve Plan Mode

Bir kodlama ajanını güvenle kullanmanın anahtarı, hangi eylemlerin onay gerektirdiğini kontrol etmektir. Gemini CLI'da bu --approval-mode bayrağıyla yönetilir ve dört değer alır: default, auto_edit, yolo ve plan. Eski --yolo / -y bayrağı kullanımdan kaldırılmış (deprecated) durumdadır; yerine --approval-mode=yolo önerilir.

Etkileşimli oturumda Shift+Tab ile modlar arasında döngü yapılır: Default → Auto-Edit → Plan. Plan Mode, CLI aktif olarak işlem yaparken veya onay diyaloğu gösterirken bu döngüden otomatik olarak çıkarılır.

Plan Mode nasıl çalışır?

Plan Mode, uygulamaya geçmeden önce çözüm tasarlamak için salt okunur bir ortamdır ve dokümana göre varsayılan olarak etkindir. Plan Mode'a üç yoldan girebilirsiniz:

• Shift+Tab ile modlar arasında geçiş,
• /plan [hedef] komutu (örneğin /plan kimlik doğrulamayı ekle moda geçer ve istemi hemen gönderir),
• Doğal dille "şunun için bir plan başlat" demek (CLI bu durumda enter_plan_mode aracını çağırır; bu araç YOLO modunda kullanılamaz).

Akış şöyle ilerler: hedefi verirsiniz, Gemini CLI kod tabanını salt okunur modda inceler, bulgularını ve önerdiği stratejiyi sizinle tartışır (gerekirse ask_user aracıyla seçenek sunar) ve sizin onayınızı beklemeden resmi planı yazmaz. Uzlaşı sağlandığında planlar dizininde ayrıntılı bir Markdown plan dosyası oluşturur; bu dosyayı Ctrl+X ile harici editörünüzde açıp düzenleyebilirsiniz. Son adımda planı "düzenlemeleri otomatik kabul et" veya "düzenlemeleri elle kabul et" seçenekleriyle onaylar ya da geri bildirim verip yineletirsiniz. Tek seferlik Plan Mode başlatmak için:

gemini --approval-mode=plan

Claude Code'da da benzer bir yapı vardır: default, acceptEdits, plan, auto, dontAsk ve bypassPermissions izin modları ve yine Shift+Tab ile döngü. Gemini CLI'ın auto_edit'i kabaca Claude Code'un acceptEdits'ine, yolo'su ise bypassPermissions'a karşılık gelir. Claude Code'un sınıflandırıcı tabanlı auto modunun ise Gemini CLI'ın belgelenmiş onay modları arasında bir karşılığı bulunmuyor.

Policy Engine: Hangi araç çalışabilir?

Daha ince taneli kontrol için Gemini CLI bir policy engine sunar. ~/.gemini/policies/ dizinine koyduğunuz her .toml dosyası yüklenir ve birleştirilir. Her kural koşullar (araç adı, argümanlar, onay modu), bir karar (allow, deny veya ask_user) ve bir öncelikten oluşur; yüksek öncelik kazanır. Resmi örnek:

[[rule]]
toolName = "run_shell_command"
commandPrefix = "rm -rf"
decision = "deny"
priority = 100

Eski --allowed-tools bayrağı kullanımdan kaldırılmıştır ve yerine bu motor önerilmektedir. Claude Code'daki permissions.allow / permissions.deny kurallarıyla aynı ihtiyaca cevap verir; yalnızca sözdizimi (TOML ve JSON) farklıdır.

Özel Komutlar: TOML ile Tekrar Kullanılabilir İstemler

Gemini CLI'da sık kullandığınız istemleri slash komutuna dönüştürebilirsiniz. Komutlar iki yerden keşfedilir: kullanıcıya özel ~/.gemini/commands/ ve projeye özel <proje>/.gemini/commands/. Aynı adlı iki komut varsa proje komutu kazanır. Alt dizinler isim alanı (namespace) oluşturur: .gemini/commands/git/commit.toml dosyası /git:commit komutu olur.

Komut dosyaları TOML formatındadır; zorunlu tek alan prompt'tur, description isteğe bağlıdır. Üç güçlü enjeksiyon mekanizması vardır:

• {{args}} — komuttan sonra yazdığınız metin buraya yerleştirilir. !{...} bloğu içinde kullanıldığında argümanlar otomatik olarak shell-escape edilir.
• !{...} — bir shell komutu çalıştırıp çıktısını isteme ekler. CLI, çalıştırmadan önce çözümlenmiş tam komutu gösterip onayınızı ister.
• @{...} — bir dosyanın içeriğini veya bir dizinin listesini isteme gömer; görsel ve PDF gibi desteklenen dosyalar çok kipli (multimodal) girdi olarak eklenir. @{...}, !{...} ve {{args}}'dan önce işlenir.

Resmi dokümandaki commit mesajı örneğini Türkçeleştirerek şöyle yazabiliriz:

# Dosya: <proje>/.gemini/commands/git/commit.toml
# Kullanım: /git:commit

description = "Stage edilmiş değişikliklerden commit mesajı üretir."
prompt = """
Aşağıdaki git diff'e göre Conventional Commits biçiminde bir commit mesajı yaz:

!{git diff --staged}
"""

Komut dosyalarını değiştirdikten sonra /commands reload ile yeniden yükleyebilir, /commands list ile tüm komutları görebilirsiniz. Claude Code'da aynı ihtiyacı Markdown tabanlı skill'ler ve slash komutları karşılar; Claude Code'daki karşılığını Agent Skills ve Slash Komutları rehberimizde anlattık. Gemini CLI'ın da ayrıca bir agent skills sistemi vardır (gemini skills list, gemini skills install <kaynak> gibi komutlarla yönetilir).

Gemini CLI'da MCP Sunucusu Nasıl Eklenir?

Gemini CLI, Claude Code gibi Model Context Protocol'ü destekler ve üç taşıma türüyle çalışır: Stdio (alt süreç başlatır), SSE ve Streamable HTTP. Sunucu eklemenin en hızlı yolu gemini mcp alt komutudur:

# Stdio tabanlı sunucu
gemini mcp add github npx -y @modelcontextprotocol/server-github

# HTTP tabanlı sunucu
gemini mcp add api-server http://localhost:3000 --transport http

# Kullanıcı kapsamında (tüm projelerde)
gemini mcp add db node db-server.js --scope user

# Yalnızca belirli araçları açmak
gemini mcp add github npx -y @modelcontextprotocol/server-github --include-tools list_repos,get_pr

# Listelemek ve kaldırmak
gemini mcp list
gemini mcp remove github

Aynı yapılandırmayı settings.json içindeki mcpServers nesnesiyle elle de yazabilirsiniz:

{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Önemli alanlar ve dikkat noktaları:

• command, url (SSE) veya httpUrl (HTTP streaming) alanlarından biri zorunludur.
• env içinde $DEGISKEN veya ${DEGISKEN} sözdizimiyle ortam değişkenlerine başvurabilirsiniz; böylece token'ları ayar dosyasına gömmek zorunda kalmazsınız.
• timeout milisaniye cinsindendir; varsayılan 600.000 ms (10 dakika).
• trust: true o sunucu için tüm araç çağrısı onaylarını atlar. Yalnızca tamamen güvendiğiniz sunucularda açın.
• includeTools / excludeTools ile araçları beyaz/kara listeye alabilirsiniz; ikisinde birden geçen araç hariç tutulur.
• Global mcp.allowed ve mcp.excluded listeleriyle hangi sunuculara bağlanılacağını merkezi olarak sınırlayabilirsiniz.

Claude Code'daki karşılığı claude mcp add --transport http <ad> <url> biçimindedir. İki araç da aynı protokolü konuştuğu için çoğu MCP sunucusu (GitHub, veritabanı, Notion vb.) her ikisinde de çalışır; yalnızca kayıt komutu ve yapılandırma dosyasının yeri değişir. MCP'nin kavramsal temelini ve Claude Code'daki kapsam (scope) mantığını Claude Code MCP rehberimizde ayrıntılı anlattık.

Hook'lar, Subagent'lar ve Eklentiler

Hook'lar

Gemini CLI'da hook'lar, ajan döngüsünün belirli noktalarında senkron çalışan betiklerdir. Bir hook olayı tetiklendiğinde CLI, eşleşen tüm hook'ların tamamlanmasını bekler. Desteklenen olaylar şunlardır:

Olay	Ne zaman tetiklenir?	Tipik kullanım
SessionStart / SessionEnd	Oturum başlarken / biterken	Bağlam yükleme, temizlik
BeforeAgent / AfterAgent	İstem gönderildikten sonra, planlamadan önce / ajan döngüsü bitince	İstem doğrulama, çıktı inceleme
BeforeModel / AfterModel	LLM isteğinden önce / yanıttan sonra	İstem değiştirme, yanıt maskeleme
BeforeToolSelection	LLM araç seçmeden önce	Kullanılabilir araçları filtreleme
BeforeTool / AfterTool	Araç çalışmadan önce / sonra	Tehlikeli işlemleri engelleme, test çalıştırma
PreCompress	Bağlam sıkıştırmadan önce	Durum kaydetme
Notification	Sistem bildirimi oluştuğunda	Masaüstü uyarısı, loglama

Hook'lar stdin üzerinden JSON alır ve stdout'a yalnızca tek bir JSON nesnesi yazmalıdır. Dokümanın "altın kural" dediği nokta kritik: stdout'a JSON'dan önce tek bir echo bile yazmak ayrıştırmayı bozar; bu durumda CLI varsayılan olarak "izin ver" davranışına düşer. Debug çıktılarını her zaman stderr'e yazın. Yapılandırma örneği:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "name": "init",
            "type": "command",
            "command": "node .gemini/hooks/init.js"
          }
        ]
      }
    ]
  }
}

Claude Code kullanıcıları bu yapıyı tanıyacaktır: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop gibi olaylar ve benzer bir matcher + hooks dizisi. Gemini CLI'ın farkı, model isteğinin kendisine (BeforeModel/AfterModel) ve araç seçimine (BeforeToolSelection) müdahale eden olaylar sunmasıdır. Claude Code'daki hook sistemini Hooks rehberimizde inceledik.

Subagent'lar

Gemini CLI'da subagent'lar, ana oturum içinde çalışan uzman ajanlardır. Her birinin kendi sistem istemi, kısıtlı araç seti ve bağımsız bağlam penceresi vardır; böylece ana konuşmanın token'larını tüketmezler. Ana ajan, görev bir subagent'ın uzmanlığına uyduğunda otomatik olarak devreder. Doğrudan yönlendirmek için istemin başına @ ile subagent adını yazarsınız. Yerleşik subagent'lardan biri kod tabanı analizi için tasarlanmış codebase_investigator'dır:

@codebase_investigator AgentRegistry ile LocalAgentExecutor arasındaki ilişkiyi çıkar.

Eklentiler (extensions)

Eklentiler; istemleri, MCP sunucularını, özel komutları ve temaları tek bir paket hâlinde dağıtmanızı sağlar. Git URL'si veya yerel yoldan kurulur:

gemini extensions install https://github.com/user/my-extension
gemini extensions list
gemini extensions update --all
gemini extensions new ./my-extension

Bu, Claude Code'daki plugin ve marketplace sisteminin karşılığıdır. Ekip içinde ortak MCP sunucusu + komut setini dağıtmak istiyorsanız her iki araçta da "paket" yaklaşımı, tek tek ayar dosyası kopyalamaktan çok daha sürdürülebilirdir.

Güvenlik: Trusted Folders, Sandbox ve Checkpointing

Trusted Folders

Bir repoyu klonladığınızda içindeki .gemini/settings.json, MCP sunucuları, hook'lar ve komutlar sizin makinenizde kod çalıştırma potansiyeline sahiptir. Trusted Folders özelliği bu riski yönetir; ancak dokümana göre varsayılan olarak kapalıdır ve kullanıcı ayarlarında açılması gerekir:

{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

Açıldığında, bir klasörde ilk kez çalıştırdığınızda CLI bir keşif aşaması yürütür; klasördeki komutları, MCP sunucularını, hook'ları, skill'leri ve ayar geçersiz kılmalarını listeleyip "klasöre güven / üst klasöre güven / güvenme" seçeneklerini sunar. Kararınız ~/.gemini/trustedFolders.json dosyasına kaydedilir. Güvenilmeyen bir klasörde CLI "güvenli mod"da çalışır: proje settings.json'u ve .env dosyaları yüklenmez, MCP sunucularına bağlanılmaz, özel komutlar yüklenmez ve her araç çağrısı onay ister. CI gibi etkileşimsiz ortamlarda güven diyaloğu gösterilemeyeceği için --skip-trust bayrağı veya GEMINI_CLI_TRUST_WORKSPACE=true ortam değişkeni kullanılır.

Sandbox

Sandbox, shell komutları ve dosya değişiklikleri gibi riskli işlemleri ana sisteminizden izole eder. -s / --sandbox bayrağı, GEMINI_SANDBOX ortam değişkeni (true|docker|podman|sandbox-exec|runsc|lxc) veya settings.json'daki tools.sandbox alanıyla açılır:

# Tek seferlik
gemini -s -p "kod yapısını analiz et"

# Docker ile kalıcı tercih
export GEMINI_SANDBOX=docker
gemini -p "projeyi derle"

macOS'ta yerleşik Seatbelt (sandbox-exec) kullanılır; varsayılan permissive-open profili yazmayı proje dizinine sınırlar, geniş okuma ve ağ erişimine izin verir. SEATBELT_PROFILE ile restrictive-* ve strict-* gibi daha sıkı profillere geçilebilir. Docker/Podman yönteminde varsayılan imaj ghcr.io/google/gemini-cli:latest'tir ve çalışma dizininiz konteyner içinde aynı mutlak yola bağlanır.

Checkpointing ve /restore

Checkpointing etkinse, dosya sistemini değiştiren bir aracı (write_file, replace gibi) onayladığınızda CLI önce bir anlık görüntü alır. Bu görüntü, kendi git deponuza dokunmayan, ~/.gemini/history/<proje_hash> altındaki gölge (shadow) bir git deposunda tutulur; konuşma geçmişi ve çalıştırılacak araç çağrısı da kaydedilir. /restore komutu kontrol noktalarını listeler ve seçtiğinizi geri yükler: dosyalar eski hâline döner, konuşma geri yüklenir ve orijinal araç çağrısı yeniden önerilir. Özellik varsayılan olarak kapalıdır ve v0.11.0'dan beri yalnızca ayar dosyasıyla açılabilir:

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

Claude Code'da checkpoint mekanizması varsayılan olarak çalışır ve /rewind komutuyla kullanılır. Gemini CLI'da ise bu özelliği bilinçli olarak açmanız gerektiğini unutmayın.

Headless Mod: Gemini CLI'ı Betiklerde ve CI'da Kullanmak

Gemini CLI, TTY olmayan bir ortamda çalıştırıldığında veya -p / --prompt bayrağıyla bir istem verildiğinde headless moda geçer: arayüz göstermeden yanıtı stdout'a yazar ve çıkar. Bu, Claude Code'un claude -p print moduna doğrudan karşılık gelir.

# Basit metin yanıtı
gemini -p "Bu kod tabanının mimarisini açıkla"

# Pipe ile girdi vermek
cat error.log | gemini -p "Bu hata neden oluştu?"

# Tek JSON nesnesi (response, stats, error)
gemini -p "Bu kod tabanının mimarisini açıkla" --output-format json

# Satır satır JSON olay akışı (JSONL)
gemini -p "Testleri çalıştır" --output-format stream-json

--output-format json çıktısı tek bir JSON nesnesidir: response (modelin nihai yanıtı), stats (token kullanımı ve API gecikme metrikleri) ve hata durumunda error. stream-json ise init, message, tool_use, tool_result, error ve result olaylarını satır satır üretir. Betiklerde dallanma yapabilmeniz için çıkış kodları da belgelenmiştir:

Çıkış kodu	Anlamı
0	Başarılı
1	Genel hata veya API hatası
42	Girdi hatası (geçersiz istem veya argüman)
53	Tur limiti aşıldı

Gerçek bir iş akışı: PR öncesi otomatik özet

Aşağıdaki Bash betiği, dokümandaki yapı taşlarını birleştirerek dalınızdaki değişiklikleri özetler, yanıtı jq ile JSON'dan ayıklar ve çıkış koduna göre davranır. Klasör güven kontrolünün açık olduğu bir CI ortamında çalışacağını varsayarak --skip-trust ekledik:

#!/usr/bin/env bash
set -uo pipefail

DIFF=$(git diff origin/main...HEAD)

echo "$DIFF" | gemini --skip-trust \
  -p "Bu diff'i Türkçe olarak 5 maddede özetle; riskli değişiklikleri ayrıca belirt." \
  --output-format json > ozet.json
KOD=$?

if [ "$KOD" -eq 0 ]; then
  jq -r '.response' ozet.json > PR_OZETI.md
  echo "Özet PR_OZETI.md dosyasına yazıldı."
elif [ "$KOD" -eq 53 ]; then
  echo "Tur limiti aşıldı; istemi daraltın." >&2
  exit 1
else
  jq -r '.error // empty' ozet.json >&2
  exit "$KOD"
fi

Aynı betiğin Claude Code versiyonu, gemini yerine claude -p, aynı --output-format json bayrağı ve tur sınırı için --max-turns kullanılarak yazılabilir; Claude Code'un JSON çıktısındaki alan adları farklı olduğu için jq filtresini uyarlamanız gerekir. Claude Code'un print modunu CLI otomasyon rehberimizde anlattık.

GitHub tarafında README, Google'ın resmi Gemini CLI GitHub Action'ını (google-github-actions/run-gemini-cli) öne çıkarıyor: otomatik PR incelemesi, issue triyajı, issue ve PR'larda @gemini-cli etiketiyle yardım ve özel zamanlanmış iş akışları. Claude Code'un GitHub Actions entegrasyonuyla aynı ihtiyaca hitap eder.

Gemini CLI ve Claude Code Karşılaştırması

İki araç kavramsal olarak birbirine çok yakın. Aşağıdaki tablo, iki aracın resmi dokümantasyonlarına göre temel yapı taşlarını yan yana koyuyor:

Konu	Gemini CLI	Claude Code
Lisans / geliştirici	Google; açık kaynak, Apache 2.0	Anthropic
Kurulum	npm install -g @google/gemini-cli, Homebrew, MacPorts (Node.js 20+)	curl -fsSL https://claude.ai/install.sh | bash (native installer) veya npm
Ücretsiz kullanım	Var (Google hesabıyla günde 1.000 istek)	Yok; Pro, Max, Team, Enterprise veya Console hesabı gerekir
Model ailesi	Gemini (Auto, Pro, Flash, Flash-Lite)	Claude (Opus, Sonnet, Haiku)
Proje talimatları	GEMINI.md (adı context.fileName ile değiştirilebilir)	CLAUDE.md; AGENTS.md da okunabilir
Ayar dosyaları	~/.gemini/settings.json, .gemini/settings.json	~/.claude/settings.json, .claude/settings.json
Onay modları	default, auto_edit, plan, yolo	default, acceptEdits, plan, auto, dontAsk, bypassPermissions
İnce taneli izinler	Policy engine (TOML kuralları)	permissions allow/deny kuralları (JSON)
Özel komutlar	TOML dosyaları, {{args}}, !{...}, @{...}	Markdown tabanlı skill'ler ve slash komutları
MCP	gemini mcp add; Stdio, SSE, Streamable HTTP	claude mcp add; stdio, SSE, HTTP
Hook'lar	BeforeTool, AfterModel, BeforeToolSelection vb.	PreToolUse, PostToolUse, Stop vb.
Geri alma	Checkpointing + /restore (varsayılan kapalı)	Checkpoint + /rewind
Headless	gemini -p, --output-format json|stream-json	claude -p, --output-format json|stream-json

Hangisini ne zaman seçmeli?

• Bütçe sıfırsa veya öğreniyorsanız: Gemini CLI'ın Google hesabıyla gelen ücretsiz katmanı, ajan tabanlı kodlamayı denemek için düşük eşikli bir giriş noktasıdır.
• Google Cloud ekosistemindeyseniz: Vertex AI kimlik doğrulaması, Code Assist lisansları ve Workspace entegrasyonu Gemini CLI'ı doğal seçim hâline getirebilir.
• Aracın kaynak koduna müdahale etmeniz gerekiyorsa: Apache 2.0 lisansı sayesinde Gemini CLI'ı fork'layıp kurum içi ihtiyaçlara göre değiştirebilirsiniz.
• Claude modellerinin kod kalitesine ve Anthropic'in ajan ekosistemine yatırım yaptıysanız: Claude Code'un auto mode, agent view, bulut oturumları, Remote Control ve zengin hook olayları gibi özellikleri — bu sitede ayrı ayrı rehberlerini yazdığımız — derin bir iş akışı sunar.
• İkisini birlikte kullanmak: Ortak bir AGENTS.md, ortak MCP sunucuları ve aynı headless iş akışı iskeletiyle iki aracı aynı repoda yan yana çalıştırmak tamamen mümkündür. Örneğin ucuz ve hızlı toplu işleri (log özetleme, doküman taslağı) bir araca, kritik refaktörleri diğerine verebilirsiniz.

Kalite konusunda en sağlıklı yöntem, kendi reponuzdan birkaç gerçek görevi iki araçta aynı istemle çalıştırıp sonucu, süreyi ve maliyeti karşılaştırmaktır.

Sorun Giderme: Sık Karşılaşılan Durumlar

• Kurumsal ağda sertifika hatası: Sorun giderme belgesi, kurum proxy'sinin sertifikasının Node.js tarafından tanınması için NODE_USE_SYSTEM_CA=1 ortam değişkenini önerir; bu yetmezse NODE_EXTRA_CA_CERTS ile kök sertifikayı gösterebilirsiniz.
• CI'da FatalUntrustedWorkspaceError: Klasör güveni açıkken etkileşimsiz ortamda güven diyaloğu gösterilemez; --skip-trust veya GEMINI_CLI_TRUST_WORKSPACE=true kullanın.
• MCP sunucusu bağlanmıyor: Klasör güvenilmez olarak işaretlenmişse MCP sunucularına hiç bağlanılmaz. Ayrıca mcp.allowed / mcp.excluded listelerini kontrol edin ve değişiklikten sonra /mcp reload çalıştırın.
• Özel komut görünmüyor: /commands reload çalıştırın; güvenilmeyen klasörde özel komutların hiç yüklenmediğini unutmayın.
• Hook çalışıyor ama etkisi yok: Betiğiniz stdout'a JSON'dan başka bir şey yazıyor olabilir; tüm log'ları stderr'e yönlendirin.

Sıkça Sorulan Sorular

Gemini CLI tamamen ücretsiz mi?

Araç açık kaynaklıdır (Apache 2.0) ve ücretsiz bir kullanım katmanı vardır: kişisel Google hesabıyla giriş yapıldığında Gemini Code Assist for individuals kapsamında günde 1.000 model isteği. Daha yüksek limitler için Google AI Pro/Ultra veya Code Assist abonelikleri, kesintisiz kullanım için ise API anahtarı ya da Vertex AI ile kullanım bazlı ödeme gerekir.

Gemini CLI'ı kurmak için hangi Node.js sürümü gerekir?

Resmi kurulum belgesine göre Node.js 20.0.0 veya üzeri gerekir. Kurulum npm install -g @google/gemini-cli, Homebrew (brew install gemini-cli) veya MacPorts ile yapılabilir; kurmadan denemek için npx @google/gemini-cli kullanılabilir.

GEMINI.md ile CLAUDE.md arasındaki fark nedir?

İkisi de aynı amaca hizmet eder: ajana kalıcı proje talimatları vermek. GEMINI.md global, çalışma alanı ve just-in-time olmak üzere hiyerarşik yüklenir ve @dosya.md ile import destekler. Gemini CLI'da context.fileName ayarıyla bağlam dosyasının adı AGENTS.md gibi bir isme çevrilebilir; Claude Code da CLAUDE.md yoksa AGENTS.md'yi okuyabildiği için tek bir ortak dosya iki araçta birden kullanılabilir.

Gemini CLI'da YOLO modu nasıl açılır?

Önerilen yol --approval-mode=yolo bayrağıdır; eski --yolo / -y bayrağı kullanımdan kaldırılmıştır. YOLO modu tüm eylemleri otomatik onaylar; bu yüzden yalnızca sandbox içinde veya tek kullanımlık ortamlarda kullanılmalıdır. Daha kontrollü bir otomasyon için policy engine kurallarını tercih edin.

Claude Code için yazdığım MCP sunucularını Gemini CLI'da kullanabilir miyim?

Evet. Her iki araç da Model Context Protocol'ü destekler; Gemini CLI Stdio, SSE ve Streamable HTTP taşımalarıyla çalışır. Sunucuyu gemini mcp add komutuyla veya settings.json içindeki mcpServers nesnesiyle kaydetmeniz yeterlidir. Değişen tek şey kayıt komutu ve yapılandırma dosyasının konumudur.

Gemini CLI'ı CI/CD içinde nasıl çalıştırırım?

Headless mod için gemini -p "istem" kullanın; makine tarafından okunacak çıktı için --output-format json veya stream-json ekleyin. Klasör güveni açıksa --skip-trust ya da GEMINI_CLI_TRUST_WORKSPACE=true gerekir. Çıkış kodları 0 (başarılı), 1 (genel/API hatası), 42 (girdi hatası) ve 53 (tur limiti aşıldı) olarak belgelenmiştir. GitHub için Google'ın resmi run-gemini-cli Action'ı da mevcuttur.

Daha Fazlası İçin

Gemini CLI'ı denedikten sonra iki aracın kesiştiği konuları Claude Code tarafında derinleştirmek isterseniz şu yazılarımızla devam edebilirsiniz: Claude Code'da MCP Rehberi, Claude Code CLI: Print Mode ve Otomasyon Rehberi ve Claude Code'da Hooks Rehberi.

Özet

Gemini CLI, Google'ın Apache 2.0 lisanslı, terminal öncelikli kodlama ajanıdır. Node.js 20+ ile kurulur; Google hesabı, API anahtarı veya Vertex AI ile çalışır ve Google hesabıyla günde 1.000 isteklik ücretsiz katman sunar. GEMINI.md, onay modları ve Plan Mode, TOML komutları, policy engine, MCP, hook'lar, subagent'lar, sandbox, checkpointing ve headless mod ile Claude Code'un yapı taşlarının çoğuna karşılık gelir. Seçim bütçenize, bulut ekosisteminize ve hangi modelin kod tabanınızda daha iyi sonuç verdiğine bağlıdır; ortak bir AGENTS.md ile ikisini aynı projede yan yana kullanmak da mümkündür.