Headless VPS'te Gemini CLI Kurulumu ve Kullanımı

Ne oluşturuluyor

Sahip olduğunuz bir sunucuda sürekli çalışan, SSH üzerinden erişilebilen ve siz dizüstü bilgisayarı kapattıktan sonra da uzun süren agent görevlerini yürütmeye devam eden bir Gemini CLI kuruluyor. Kurulum üç komuttan oluşur. Asıl çalışma, masaüstü varsayımlarının ortadan kaldırılmasını gerektirir: Google'ın CLI aracı oturum açmanız için bir tarayıcı açmak ister, ancak sunucunuzda tarayıcı yoktur. Bu nedenle kılavuzun büyük bölümü headless kullanım yolunu, dağıtımın sağlayamayacağı güncel bir Node sürümünü, root gerektirmeyen global npm kurulumunu, shell geçmişine yazılmasını önleyecek API key ile tarayıcısız kimlik doğrulamayı ve kopan bir SSH oturumunun çalışan görevi sonlandırmaması için tmux kullanımını ele alır.

Gemini CLI, Google'ın Gemini modelleriyle iletişim kuran ve çalışma dizinindeki dosyaları okuyup yazabilen, shell komutlarını çalıştırabilen ve araçları kullanabilen açık kaynaklı (Apache-2.0) bir Node programıdır (@google/gemini-cli). VPS üzerinde sürekli erişilebilir, çalışır durumda bırakılabilen küçük bir agent görevi görür. Bu nedenle burada kullanılan account ve sunucuda tutulan credentials, tek bir ayardan daha önemlidir.

Ön gereksinimler ve dikkat edilmesi gerekenler

• root veya sudo yetkisine sahip, temiz bir Ubuntu 24.04 KVM VPS. Herhangi bir KVM planı yeterlidir; CLI oldukça hafiftir, boşta çalışırken birkaç yüz MB RAM tüketir.
• Node.js 20 veya daha yeni bir sürüm. Bu kesin bir alt sürüm sınırıdır ve dağıtım paketleri bu sürümün altındadır, sonraki bölüme bakınız. Node 20'nin ömrü 30 Nisan 2026 tarihinde dolmuştur, bu nedenle 24 sürümünü kurunuz.
• Google API'lerine giden HTTPS (443 numaralı port) trafiği. Gelen portlara ihtiyaç yoktur; bu bir sunucu değil istemcidir, bu nedenle güvenlik duvarında herhangi bir delik açmanız gerekmez.
• Sunucuda tarayıcı gerektirmeyen bir kimlik doğrulama yöntemi: Google AI Studio üzerinden alınmış ücretli bir Gemini API anahtarı veya başsız (headless) bir sistemde terminale kod yapıştırmanızı gerektiren Google oturum açma yöntemi. API anahtarı yöntemi, betikler ve gözetimsiz çalıştırmalar için ölçeklenebilir olan yoldur.
• Yalnızca --sandbox izolasyonu istiyorsanız Docker veya Podman. İsteğe bağlıdır, bölümün sonunda ele alınmıştır.

Şu an herkesi yakalayan temel sorun tarayıcı değil, hesap türüdür. Google, 19 Mayıs 2026 tarihinde yaptığı duyuru ile 18 Haziran 2026 tarihinden itibaren Gemini CLI'ın Google AI Pro ve Ultra aboneleri ile ücretsiz kullanıcılar için istekleri yanıtlamayı durduracağını ve bu kullanıcıları Antigravity CLI (agy) aracına yönlendireceğini açıklamıştır. Gemini CLI; ücretli Gemini API anahtarları, Gemini Enterprise Agent Platform API anahtarları ve bir organizasyonun Gemini Code Assist Standard veya Enterprise lisansları ile çalışmaya devam etmektedir. Başlamadan önce kimlik doğrulama yolunuza karar veriniz.

Not: Dağıtım paketi çok eski

Ubuntu 24.04, kendi depolarında Node 18.19.1 sürümünü ve bununla eşleşen npm 9.2.0 sürümünü sunar. Gemini CLI'ın package.json dosyası engines: { node: ">=20" } gereksinimini belirtir; npm varsayılan olarak bir uyumsuzluk durumunda işlemi durdurmaz, kurulumu yapar ve aradaki farkı belirten bir uyarı yazdırır:

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@google/gemini-cli@0.50.0',
npm WARN EBADENGINE   required: { node: '>=20' },
npm WARN EBADENGINE   current: { node: 'v18.19.1', npm: '9.2.0' }
npm WARN EBADENGINE }

Bu uyarıyı görmezden gelip devam ederseniz CLI desteklenmeyen bir çalışma zamanında çalışır. CLI, Node 20+ sürümünde bulunmasını beklediği bir API'ye ulaştığı anda hatalı davranır veya çöker. Node 18 ayrıca Nisan 2025 itibarıyla ömrünü tamamlamıştır (end-of-life), dolayısıyla her iki durumda da çıkmaz bir yoldur. CLI'ı kurmadan önce güncel bir LTS sürümü kurun. İki temiz yöntem mevcuttur: NodeSource (sistem genelinde imzalı bir apt deposu) veya nvm (kullanıcı bazlı bir sürüm yöneticisi). Birini seçin.

Sunucudaki her kullanıcının Node'a erişmesini istiyorsanız NodeSource yöntemini kullanın:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

CLI gereksinimini karşılamak için node --version komutu v20.x veya daha yüksek bir sürüm çıktısı vermelidir. Ancak Node 20, 30 Nisan 2026 itibarıyla ömrünü tamamladığından, güncel aktif LTS olan v24.x sürümünü hedefleyin. Node 26'nın 28 Ekim 2026 tarihinde aktif LTS olması planlanmaktadır. Güncel kurulum betiği için NodeSource sayfasını kontrol edin; URL içindeki setup_24.x ifadesi, daha yeni bir LTS sürümü yayınlandığında güncellenmesi gereken kısımdır.

Node'u yalnızca bir kullanıcının ev dizininde tutmak ve sudo ile müdahale etmemek istiyorsanız nvm yöntemini kullanın:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version

Bu URL içindeki v0.40.1 ifadesi, bu metin yazıldığı sırada günceldi; en son sürüm için nvm'in README dosyasını kontrol edin ve komutu çalıştırmadan önce sürümü güncelleyin. nvm'in bu iş için gerçek bir avantajı vardır: Node'u ve global paketlerini ~/.nvm dizini altına kurar, bu sayede bir sonraki bölümde bahsedilen global kurulum izin sorunları hiçbir şekilde yaşanmaz. nvm yolunu seçerseniz, npm-prefix adımını atlayabilirsiniz.

CLI'yi sudo npm -g olmadan kurma

İlk akla gelen komut sudo npm install -g @google/gemini-cli olur. Bunu kullanmayın. root sahibi bir global prefix, sonraki her kurulumda izin hatalarına neden olur ve npm cache içinde aylar sonra sorun çıkarabilecek root sahibi dosyalar bırakır. Sistem Node'u ile düz (npm install -g olmadan) npm install -g çalıştırıldığında diğer hata alınır:

npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/@google
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@google'

Bu hata, npm'nin kullanıcınızın yazma izni olmayan /usr/lib konumuna yazmaya çalıştığını gösterir. Çözüm sudo kullanmak değil, npm'nin global prefix değerini home dizininize yönlendirmektir. Böylece global kurulumlar sahibi olduğunuz bir konuma yapılır:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
gemini --version

~/.bashrc kullanılması, ~/.profile yerine, bilinçlidir: İki bölüm sonra CLI'yi içinde çalıştıracağınız tmux, ~/.bashrc dosyasını okuyan ve ~/.profile dosyasını atlayan bir non-login shell başlatır. Bu nedenle yanlış dosyadaki bir PATH satırı, tam ihtiyaç duyduğunuz yerde gemini değerini görünmez bırakır. gemini --version komutunun bir sürüm numarası yazdırması yeterli testtir. Bunun yerine gemini: command not found alırsanız PATH export işlemi uygulanmamıştır; hata senaryolarına bakın. nvm kullanıyorsanız prefix satırlarını tamamen atlayın: nvm global paketleri zaten home dizininizin altında kurar.

Daha önce bir noktada sudo npm çalıştırdıysanız ve şimdi Your cache folder contains root-owned files görüyorsanız, sudo chown -R $(id -u):$(id -g) ~/.npm ile bir kez düzeltin.

Headless kimlik doğrulama sorunu ve çözüm yolları

gemini komutunu ilk kez etkileşimli olarak çalıştırdığınızda, sizi Google hesabınızla oturum açmaya yönlendirir. Masaüstü ortamında bu işlem bir tarayıcı sekmesi açar. Başsız (headless) bir Linux VPS üzerinde ise CLI önce bir ekran olup olmadığını kontrol eder; DISPLAY, WAYLAND_DISPLAY veya MIR_SOCKET değişkenlerinden hiçbiri ayarlanmamışsa tarayıcı başlatmayı denemez. Bunun yerine bir oturum açma bağlantısı yazdırır ve bir kod yapıştırmanızı bekler:

Please visit the following URL to authorize the application:

https://accounts.google.com/o/oauth2/v2/auth?...

Enter the authorization code:

Bu akış standart SSH üzerinden çalışır ancak her seferinde bir tarayıcıya erişim gerektirir. Ayrıca 18 Haziran 2026 tarihinden itibaren, bu yöntem yalnızca Gemini CLI tarafından desteklenen Google hesaplarında çalışmaktadır.

Bu sorunu aşmanın iki geçerli yolu vardır.

Birinci yol bir API anahtarı kullanmaktır; sunucular için varsayılan ve doğru yöntem budur. Gemini CLI artık ücretsiz kullanımı desteklemediğinden, faturalandırması aktif bir proje üzerinde Google AI Studio (aistudio.google.com) üzerinden bir anahtar oluşturun ve bunu CLI'ya bir ortam değişkeni olarak tanımlayın; CLI, GEMINI_API_KEY değişkenini okur ve tarayıcı akışını tamamen atlar. Şimdi "geçmişte tutmama ve herkesin okuyabileceği dosyalara yazmama" kısmına gelelim. Komut satırına export GEMINI_API_KEY=AIza... yazmayın, bu komut ~/.bash_history dosyasına düz metin olarak kaydedilir. Ayrıca anahtarı başkalarının okuyabileceği dosyalara koymayın. Anahtarı, kabuğun başlangıçta kaynak olarak aldığı 600 modlu bir dosyaya yazın:

umask 077
printf 'export GEMINI_API_KEY=%s\n' 'AIzaSyYOUR_KEY_HERE' > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrc

chmod 600, dosyayı yalnızca sizin kullanıcınızın okuyabileceği anlamına gelir. Anahtarın ortama ulaştığını printenv GEMINI_API_KEY ile doğrulayın; eğer çıktı boşsa, CLI anahtarı kullanmak yerine kimlik doğrulama seçicisine geri döner. Eğer bu düzeni tercih ederseniz, CLI ~/.gemini/ dizinindeki .env dosyasını da okur; aynı kural burada da geçerlidir, bu yüzden chmod 600 ~/.gemini/.env komutunu kullanın.

İkinci yol ise Google ile oturum açma yöntemidir; bu yöntem başsız bir sunucuda herhangi bir tünel veya açık port gerektirmez. 18 Haziran 2026 itibarıyla bu yöntem temel olarak bir organizasyonun Gemini Code Assist Standard veya Enterprise lisansı için kullanışlıdır (ayrıca GOOGLE_CLOUD_PROJECT değişkenini ayarlayın); ücretsiz kişisel hesaplar ile Google AI Pro veya Ultra abonelikleri artık desteklenmemektedir. CLI'yı normal bir SSH oturumu üzerinden başlatın ve Google ile oturum açmayı seçin:

gemini

Ekranda yazdırılan URL'yi dizüstü bilgisayarınızdaki tarayıcıya kopyalayın ve onaylayın. Google sizi bir yetkilendirme kodu gösteren https://codeassist.google.com/authcode adresine yönlendirir; bu kodu VPS üzerindeki Enter the authorization code: istemine yapıştırın, oturum açma işlemi tamamlanır. Sunucu tarafında herhangi bir geri çağırma (callback) beklenmediği için sabitlenmesi gereken bir port veya ayarlanması gereken bir ssh -L yoktur. OAUTH_CALLBACK_PORT değişkeni yalnızca CLI bir ekran algıladığında kullandığı yerel döngü (loopback) akışı için önemlidir. Eğer X11 yönlendirmesi (ssh -X) ile bağlandıysanız, DISPLAY ayarlanmış olur ve CLI, sunucu üzerinde http://127.0.0.1:PORT/oauth2callback adresine yönlendirme yaparak bu yerel döngü akışını kullanır; kod yapıştırma akışını zorlamak için NO_BROWSER=true gemini komutunu çalıştırın. Bu yöntem çalışır ancak bir tarayıcı başında olmanızı gerektirdiği için betikler (scripts) için uygun değildir. Çalışır durumda bırakacağınız her şey için API anahtarını kullanın.

AI Studio yerine Vertex AI veya bir Google Cloud projesi kullanıyorsanız, GOOGLE_GENAI_USE_VERTEXAI=true ile birlikte GOOGLE_API_KEY değişkenini veya Code Assist lisansı için GOOGLE_CLOUD_PROJECT değişkenini ayarlayın; aynı ortam değişkeni disiplinini ve aynı 600 modlu dosya yapısını uygulayın.

SSH oturumunun kesilmesi durumunda işlemin sonlanmaması için tmux içinde çalıştırın

Doğrudan SSH kabuğunuzdan başlattığınız bir gemini süreci, o kabuğun bir alt sürecidir. Bağlantının kopması, dizüstü bilgisayarın kapanması, Wi-Fi bağlantısının kesilmesi veya boşta kalma zaman aşımı gibi durumlarda sshd sözde terminali (pseudo-terminal) kapatır, kabuk SIGHUP sinyali alır ve CLI üzerindeki süreç sonlanır. Dosya düzenleme işleminin onuncu dakikasında süreç ölür ve yeniden bağlandığınızda kurtarabileceğiniz bir süreç kalmaz.

tmux, kabuğun sahipliğini sshd yerine kendisi alarak bu sorunu çözer. Bu, uzak bir VPS üzerinde tmux içinde bir yapay zeka kodlama aracısı çalıştırmak ile aynı yöntemdir ve burada da aynı şekilde çalışır:

sudo apt install -y tmux
tmux new -A -s gemini
# inside the session:
gemini
# detach with Ctrl-b then d, the task keeps running
# reconnect later from any machine:
tmux attach -t gemini

tmux new -A -s gemini, eğer mevcutsa gemini isimli bir oturuma bağlanır, mevcut değilse bu oturumu oluşturur; bu nedenle her girişten sonra çalıştırılması gereken tek komut budur. İçerideki kabuk, SSH oturumunuza değil, arka planda çalışan tmux sunucusuna aittir; bu nedenle bağlantının kopması CLI'ın çalışmaya devam etmesini sağlar. Yeniden bağlandığınızda, attach komutuyla kaldığınız yerden devam edebilirsiniz. Eğer bir sunucuda her biri bir tmux oturumuna ait olacak şekilde birden fazla aracı oturumu çalıştırırsanız, Claude Code'un aksine aynı VPS üzerinde bir oturumun diğerine metin aktarabildiği bir yapı burada mevcut değildir; bu yüzden her Gemini işini bağımsız tutun veya bunları disk üzerindeki dosyalar aracılığıyla koordine edin.

Etkileşimli olmayan, betik tabanlı çalıştırmalar için Gemini CLI'ın başsız (headless) modu mevcuttur: gemini -p "summarise the failing tests in this repo" bir yanıt yazdırıp çıkar, --output-format json ise başka bir yere yönlendirilebilecek (pipe) makine tarafından okunabilir bir çıktı verir. API anahtarı ile başsız mod, uzun süreli bir toplu işi çalıştıran bir tmux oturumunda veya bir cron girdisinden tetiklendiğinde tam olarak ihtiyaç duyduğunuz şeydir. Ancak bir uyarı mevcuttur: bir cron işi giriş dosyalarınızı (login files) kaynaklamaz (source etmez). Bu nedenle crontab satırına kendi GEMINI_API_KEY değerini tanımlayın (veya komutun ~/.gemini_env dosyasını kaynaklamasını sağlayın), aksi takdirde kimlik bilgileri eksik olduğu için çalıştırma başarısız olur.

Üretim ortamının da çalıştığı bir sunucuda korumalı alan (sandboxing) ve izinler

Kabuk erişimine sahip bir aracı, bir kabuktur. Gemini CLI komutları çalıştırabilir ve varsayılan olarak her riskli komuttan önce onay ister; ancak kullanıcılar genellikle --yolo (her araç çağrısını otomatik onayla) seçeneğine yönelir. Bu durumda aracı; dosyaları silebilir, git deposuna push yapabilir veya çalıştığı kullanıcının tüm yetkileriyle dahili servislere erişebilir. Üretim ortamının da çalıştığı bir sunucuda bu durum, varsayımsal değil, gerçek bir etki alanıdır.

Sağladıkları fayda sırasına göre üç kontrol mekanizması:

• Aracı, yetkisiz ve özel bir kullanıcı olarak çalıştırın. root kullanıcısı veya sudo üyesi olmamalıdır. Kendi ev dizinine sahip bir agent kullanıcısı oluşturun, Node ve CLI kurulumunu burada yapın; böylece yanlış anlaşılan bir komut yalnızca bu hesapla sınırlı kalır. Bu, alınabilecek en yüksek değerli karardır.
• Üretim ortamı kimlik bilgilerini sunucuda tutmayın. Üretim ortamına ait ~/.aws/credentials anahtarları, üretimden kopyalanmış .env dosyaları veya kritik öneme sahip herhangi bir yere yazma erişimi olan veritabanı şifreleri sunucuda bulunmamalıdır. Araca yalnızca test (staging) veya salt okunur yetkiye sahip kimlik bilgileri verin.
• Yerleşik korumalı alanı (sandbox) kullanın. Docker veya Podman yüklüyken, gemini --sandbox (veya GEMINI_SANDBOX=docker) aracın araç çağrılarını, ana bilgisayar dosya sisteminin geri kalanını değil, yalnızca mevcut proje dizinini bağlayan bir container içinde çalıştırır. Bu, yetkisiz kullanıcı yönteminin yerini tutmaz ancak aynı VPS üzerinde gerçek işler yürütülürken güçlü bir ikinci katman sağlar.

Gemini CLI'ı diğer self-hosted araçlarla birlikte çalıştırıyorsanız, örneğin aynı VPS üzerinde araca araçlar sunan bir MCP sunucusu kullanıyorsanız, eklenen her yeteneği aracının erişebileceği yeni bir yüzey olarak değerlendirin ve araca verilen token'ları tam olarak tek bir görevle sınırlandırın.

Kota, maliyet ve seçilen kimlik doğrulama yolu

Kimlik doğrulama yolu, faturalandırmanızın nasıl yapılacağını ve 18 Haziran 2026 tarihinden itibaren hizmet alıp alamayacağınızı belirler. Google'ın duyurusuna göre, bu tarihten itibaren Gemini CLI; Google AI Pro ve Ultra aboneleri ile kişisel hesapların ücretsiz katmanını ve faturalandırılmamış API anahtarlarını kullananlar dahil olmak üzere ücretsiz hizmet alan herkes için istekleri karşılamayı durdurmuştur. Servis; token başına ücretlendirilen ücretli Gemini API anahtarları ve Gemini Enterprise Agent Platform API anahtarları ile Gemini Code Assist Standard veya Enterprise lisansına ya da diğer Google Cloud erişimlerine sahip olan ve Google Cloud üzerinden faturalandırılan kurumlar için kullanılabilir durumdadır. Her katmanın hala dakika ve gün bazlı limitleri bulunmaktadır; bu limitler aşıldığında, zaman aralığı sıfırlanana kadar istekler hız sınırı hatası döndürür.

İki pratik not: Döngü içindeki denetimsiz bir aracı, kotayı hızla tüketebilir; bu nedenle bir cron job görevine güvenmeden önce ilk birkaç seferde aracı izleyin. Sunucu tarafındaki bir model tercihinizin nedeni Google'ın barındırılan modelleri yerine gizlilik veya sınırsız çıkarım ise, bu farklı bir araç gerektirir; Ollama ile bir VPS üzerinde açık kaynaklı bir LLM'i kendi sunucunuzda barındırmak, ağırlıkları ve istemleri kendi makinenizde tutmanızı sağlar ancak bunun bedeli Gemini'dan çok daha küçük bir model çalıştırmaktır.

Güncel tutulması

Gemini CLI sık sık yeni sürümler yayınlar. Kullanıcıya ait bir prefix içine kurulduğu için güncellemeler için sudo gerekmez:

npm install -g @google/gemini-cli@latest
gemini --version

Sürüm kanalları bulunur: @latest kararlı sürümdür, @preview haftalık önizlemedir, @nightly en güncel geliştirme sürümüdür. Bağımlı olduğunuz sistemlerde @latest sürümüne sabitleyin. nvm kullanıldığında global paketler etkin Node sürümünün altında tutulur. Bu nedenle Node sürümünü değiştirmek için nvm use kullandıktan sonra CLI'yi yeniden kurmanız gerekebilir. Her yamayı takip etmek yerine sürüm notlarını okuyun.

Hata modları ve kesin dizgeler

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' } ve ardından CLI'ın çalışma zamanında çökmesi. Node sürümü çok eskidir; dağıtımın sunduğu 18.19.1 sürümü ömrünü tamamlamıştır. NodeSource veya nvm üzerinden güncel bir LTS sürümü kurun (Node 20, CLI'ın alt sınırını karşılar ancak Nisan 2026 itibarıyla ömrünü tamamlamıştır), node --version ile kurulumu doğrulayın. Eğer sistemde birden fazla Node sürümü yüklüyse, which node komutunun /usr/bin/node yerine yeni sürüme işaret ettiğinden emin olun.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. Root sahipliğindeki bir dizine global kurulum yapılmıştır. Kurulumu sudo ile çalıştırmayın; npm config set prefix ~/.npm-global değişkenini ayarlayın, ~/.npm-global/bin dizinini PATH yoluna ekleyin ve normal kullanıcı yetkileriyle yeniden kurun. Eğer daha önceki bir sudo npm işlemi root sahipliğinde önbellek dosyaları (Your cache folder contains root-owned files) bıraktıysa, sudo chown -R $(id -u):$(id -g) ~/.npm komutunu çalıştırın.

Failed to open browser veya http://127.0.0.1:PORT adresine işaret eden bir redirect_uri. CLI bir görüntüleme değişkeni bulmuştur (genellikle ssh -X üzerinden) ve geri döngü (loopback) akışını başlatmıştır; bu akışın geri çağrısı sunucuya ulaşır. Kod yapıştırma akışını tetiklemek için NO_BROWSER=true gemini komutunu çalıştırın veya API anahtarı yolunu (GEMINI_API_KEY) kullanın. Standart bir SSH oturumunda bunun yerine Enter the authorization code: görmelisiniz; URL'yi yerel tarayıcınızda onaylayın ve Google'ın size gösterdiği kodu yapıştırın.

SSH bağlantısı koptuğunda sürecin kaybolması. gemini komutunu doğrudan SSH kabuğu üzerinden çalıştırdınız; bu nedenle süreç, kabuğun bir alt süreci olarak çalıştı ve bağlantı kesildiğinde pty ile birlikte sonlandı. Kurtarılacak bir veri yoktur. Her oturumu tmux new -A -s gemini ile başlatın ve CLI'ı bu oturumun içinde çalıştırın.

Anahtar ayarlı olmasına rağmen kimlik doğrulamanın başarısız olması, CLI'ın tekrar kimlik doğrulama seçimine dönmesi veya bir isteğin HTTP 400 ile API key not valid döndürmesi. Anahtar, CLI'ın gördüğü ortam değişkenlerinde bulunmamaktadır. printenv GEMINI_API_KEY ile durumu doğrulayın; eğer boşsa, ~/.gemini_env dosyanız hiçbir zaman kaynaklanmamıştır (sourced). Satırın, etkileşimli kabukların (tmux dahil) okuduğu ancak cron ve diğer etkileşimli olmayan kabukların okumadığı ~/.bashrc dosyasında olduğundan emin olun. Anahtar değeri içindeki fazladan bir boşluk veya tırnak işareti de API key not valid hatasına neden olur.

429 / RESOURCE_EXHAUSTED / hız sınırı (rate-limit) mesajı. Kimlik doğrulamanızın kullandığı katmana ait kotayı aştınız. Pencerenin sıfırlanmasını bekleyin, aracı yavaşlatın veya ücretli bir API anahtarına geçiş yapın. Yeniden deneme döngüsünde takılı kalan bir aracı bu hatayı tetiklemeye devam eder; aracı durdurun ve ne yaptığını inceleyin.

FAQ

Başsız (headless) bir sunucuda Gemini CLI kimlik doğrulaması nasıl yapılır?

Tarayıcı girişi yerine ücretli bir API anahtarı kullanın. Google AI Studio üzerinde faturalandırılan bir proje altında anahtar oluşturun, bu anahtarı shell'inizin kaynak olarak kullandığı (export GEMINI_API_KEY=...) 600 modlu bir dosyaya kaydedin; böylece CLI, OAuth tarayıcı akışını tamamen atlayacaktır. Eğer bunun yerine, örneğin Code Assist Standard veya Enterprise lisansı ile Google üzerinden giriş yaparsanız, başsız bir makinedeki CLI bir URL çıktısı verir; bu URL'yi dizüstü bilgisayarınızda açıp onaylayın ve Google'ın gösterdiği kodu Enter the authorization code: istemine yapıştırın. Sabitlenecek bir port veya tünel yoktur, ancak bir tarayıcı başında bulunmanızı gerektirdiği için betikler (scripts) için uygun değildir. Ücretsiz kişisel hesaplar, 18 Haziran 2026 tarihinden bu yana Gemini CLI tarafından desteklenmemektedir.

npm global kurulumu neden sudo istiyor ve bunu nasıl önleyebilirim?

Çünkü npm'in varsayılan global öneki /usr/lib/node_modules dizinidir ve kullanıcınızın buraya yazma yetkisi yoktur; bu nedenle normal bir npm install -g komutu EACCES hatasıyla başarısız olur. Yanlış çözüm sudo npm -g kullanmaktır; bu, daha sonraki kurulumları bozan root sahipli dosyalar bırakır. Doğru çözüm, öneki ev dizininize (npm config set prefix ~/.npm-global) yönlendirmek ve bunun bin dizinini PATH değişkenine eklemektir ya da global paketleri otomatik olarak ev dizininiz altına kuran nvm kullanmaktır.

Bağlantımı kestiğimde Gemini CLI'ın çalışmaya devam etmesini nasıl sağlarım?

tmux içinde çalıştırın. SSH shell'inizden başlatılan bir süreç, bağlantı koptuğunda sonlanır çünkü bu süreç shell'in bir alt öğesidir; tmux ise shell'i bağlantı kesilse bile hayatta kalan bağımsız bir sunucu altında çalıştırır. tmux new -A -s gemini komutunu kullanın, içinde gemini komutunu çalıştırın, Ctrl-b d ile ayırın ve daha sonra tmux attach -t gemini ile tekrar bağlanın.

Gemini CLI'ı üretim (production) ortamındaki bir makinede çalıştırmak güvenli midir?

Sadece dikkatli bir şekilde, çünkü shell erişimine sahip bir aracı, çalıştırıldığı kullanıcının yapabildiği her şeyi yapabilir. CLI'ı sudo yetkisi olmayan özel ve ayrıcalıksız bir kullanıcı olarak çalıştırın, üretim kimlik bilgilerini makinede tutmayın, --yolo otomatik onay özelliğinden kaçının ve araç çağrılarını ana makineden izole etmek için --sandbox (Docker veya Podman) kullanın. Çalıştığı hesap, ayarladığınız herhangi bir bayraktan (flag) daha önemlidir.

Gemini CLI için herhangi bir güvenlik duvarı portu açmam gerekiyor mu?

Hayır. Google API'lerine giden HTTPS çağrılarını yapan bir istemci olduğu için 443 numaralı giden portuna ihtiyaç duyar ancak gelen (inbound) portlara ihtiyaç duymaz. Başsız bir makinedeki Google girişi de herhangi bir port gerektirmez: sunucuda bir geri arama (callback) almak yerine kodu terminale geri yapıştırırsınız. Gelen trafiği kapalı tutun.