Kullanım Kılavuzu

// 01

comrade nedir?

comrade, terminalde ne yazacağınızı bilmenize gerek kalmadan, düz Türkçe veya İngilizce ile isteğinizi yazdığınızda sizin yerinize doğru komutu üreten bir yapay zeka yoldaşıdır. Siz "docker kur" ya da "8080 portunu kim kullanıyor bul" dersiniz; comrade durumu (işletim sisteminiz, son hatanız, çalışma dizininiz gibi) toplar, bir yapay zeka sağlayıcısına sorar, adım adım bir plan üretir ve seçtiğiniz davranış moduna göre bu planı ya çalıştırır, ya her adımda size sorar ya da sadece açıklar.

Hiçbir komut sizin bilginiz/onayınız olmadan sinsice çalışmaz — bkz. 3 davranış modu ve güvenlik.

// 02

Kurulum

En hızlı yol, işletim sisteminize göre tek satırlık bir script'tir:

macOS / Linux

curl yok mu? wget de olur

Windows (PowerShell)

Homebrew (macOS/Linux) ve Scoop (Windows) kullananlar için:

Homebrew

Scoop

scoop bucket add firatkutay https://github.com/firatkutay/scoop-bucket
scoop install comrade

Node.js/npm zaten kuruluysa, bu bir alternatif kurulum yoludur (yukarıdaki script/Homebrew/Scoop kanalları birincil kalır):

npm

Önceden derlenmiş binary kurar — derleme araç zinciri gerekmez. Dikkat: bu şekilde kurulursa comrade upgrade kendi kendini güncellemeyi reddeder — bunun yerine npm update -g cli-comrade kullanın.

Script'ler indirdiği paketi kurmadan önce checksum'a karşı doğrular; kurulum dizini PATH'inizde değilse otomatik olarak ekler (yeni bir terminal gerekir). Diğer kanallar (.deb/.rpm, ham arşivler, kaynaktan derleme) ve ortam değişkeni referansı için: docs/INSTALL.md.

comrade'ı tamamen kaldırmak isterseniz (API anahtarları dahil), kanal başına komut ve kalan dosyalar için: docs/INSTALL.md.

Kurulumun bittiğini doğrulamak için yeni bir terminal açıp:

// 03

İlk çalıştırma — bir sağlayıcı ayarlayın

comrade'i kurar kurmaz hiçbir yapay zeka komutu (do/fix/explain/chat) çalışmaz — çünkü henüz bir sağlayıcı anahtarı yok. İki yol var:

A) Bulut sağlayıcı (API anahtarı ile) — en hızlı yol

Bu, sizden API anahtarınızı ister, saklamadan önce küçük bir test isteği gönderir ve anahtarı işletim sistemi keychain'inde saklar. google (Gemini) için de aynı şekilde çalışır: comrade auth login google.

OpenAI, Qwen, Groq, Mistral, GLM/Zhipu, Kimi/Moonshot, OpenRouter, LM Studio gibi OpenAI-uyumlu bir sağlayıcı kullanacaksanız:

Akış şöyle işler:

1. API anahtarınızı sorar.
2. Hâlâ varsayılan OpenAI adresindeyseniz, sağlayıcının adresini (base_url) sorar — sadece Enter'a basarsanız OpenAI'de kalırsınız.
3. Girdiğiniz adres OpenAI'den farklıysa ve henüz bir model seçilmediyse, kullanmak istediğiniz modelin adını sorar (ör. qwen-plus) — boş bırakabilirsiniz, sonra comrade config set llm.model <model> ile ayarlarsınız.
4. Anahtarı test eder: anahtar reddedilirse (401/403) hiçbir şey kaydedilmez; "model bulunamadı" (404) hatası alırsa anahtar yine de kaydedilir ve size comrade config models çalıştırıp doğru modeli seçmenizi söyler; başka bir hata olursa yine kaydeder ama doğrulayamadığını belirtir.

Girişten sonra, giriş yaptığınız sağlayıcı etkin sağlayıcınız olur (comrade "..." artık onu kullanır ve girdiğiniz model ona uygulanır).

comrade auth login openai_compat
# API key: <anahtarınız>
# Provider address (base_url) [Enter = OpenAI]: https://dashscope-intl.aliyuncs.com/compatible-mode/v1
# Model [Enter = skip]: qwen-plus

B) Yerel / çevrimdışı (Ollama) — anahtar gerekmez

Kendi makinenizde çalışan bir modeli kullanmak isterseniz:

ollama pull llama3.1                     # önce modeli Ollama ile indirin
comrade config set llm.provider ollama
comrade config set llm.model llama3.1    # opsiyonel — boş bırakırsanız kurulu bir model otomatik seçilir

Ollama kurulu değilse ollama.com'dan kurun — comrade bunu sizin için kurmaz. comrade auth login ollama diye bir şey YOKTUR ve reddedilir; bu sağlayıcının hiç anahtara ihtiyacı yoktur.

Kontrol edin

comrade auth status    # hangi sağlayıcılarda anahtar var, gösterir (değerleri asla yazdırmaz)
comrade doctor         # yapılandırmanızı uçtan uca kontrol eder
comrade doctor --live  # + gerçek, doğrulanmış bir istek gönderir (bir token harcar)

Ayrıntılı sağlayıcı/model referansı için: docs/CONFIGURATION.md.

// 04

3 davranış modu

comrade'in ne kadar "kendi başına" davranacağını belirleyen üç mod var:

Modu değiştirme yolları:

// 05

Ana işler

comrade fix

Son başarısız komutunuzu teşhis eder ve bir düzeltme önerir. Bunun otomatik çalışması için önce shell entegrasyonunu kurmanız GEREKİR:

...ve ardından terminalinizi yeniden başlatın — kanca (hook) yeni açılan oturumlara uygulanır, mevcut oturuma değil. Kurulmadıysa veya yeni bir terminal açmadıysanız, comrade fix hiçbir hatayı otomatik yakalamaz; bunun yerine:

ya da hatayı doğrudan terminale yapıştırmanız istenir (yapıştırma modu her zaman çalışır, kancaya ihtiyaç duymaz).

comrade "<düz metin istek>"

Varsayılan komuttur, ayrı bir alt komut yazmanıza gerek yoktur (comrade do "..." ile aynı):

comrade explain "<komut>"

Bir komutu ÇALIŞTIRMADAN, bayrak bayrak açıklar. Korkutucu bir komutu anlamanın güvenli yolu:

Komut tire (-) ile başlıyorsa: comrade explain -- <komut>.

comrade chat

Bağlamı koruyan interaktif bir sohbet oturumu (gerçek bir terminal/TTY gerektirir). Oturum içi komutlar:

// 06

Günlük yardımcılar

• comrade undo — geri alınabilir son işlemi tersine çevirir, ya da elle yapılacak adımları gösterir. Her zaman ask modunda çalışır — bir --yolo yolu YOKTUR, çünkü bir geri alma orijinal işlemden daha az değil, daha fazla dikkat ister. comrade undo --list son geri alınabilir işlemleri listeler; audit.retention_days (varsayılan 90 gün) ile sınırlıdır.
• comrade history — denetim kaydından (audit log) son çalıştırılan komutları gösterir (--limit 50 gibi).
• comrade config — get <anahtar> / set <anahtar> <değer> / list (her anahtarın kaynağını da gösterir) / models (etkin sağlayıcı için modelleri listeler, seçip llm.model'e kaydeder) / edit ($EDITOR'da açar, yoksa vi/Windows'ta notepad) / path (dosya yolunu yazdırır).
• Profiller — iş/kişisel gibi ayrı yapılandırmalar için: comrade config profile add work --from-current, comrade config profile use work, ya da tek seferlik --profile work. Dikkat: config set dosya-seviyesi değeri değiştirir, AKTİF PROFİLİ değil — bir profil İÇİNDEKİ bir anahtarı değiştirmek için comrade config profile set work llm.provider openai_compat kullanın. --profile bayrağı, ham argüman alan alt komutlarda çalışmaz: config set ve config profile set kullanım hatası verir, explain ise onu açıklanan komut metnine karıştırır ve isteği yine varsayılan profille çalıştırır; bu üçünde onun yerine COMRADE_PROFILE=work kullanın (issue #27).
• Plan önizlemesi — general.plan_review=ask ayarlayın (ya da --review verin) ki adımlar çalışmadan önce yeniden sıralayabileceğiniz/atlayabileceğiniz/düzenleyebileceğiniz interaktif bir önizleme ekranı görün (ask modda, çok adımlı planlarda); --no-review bunu her zaman kapatır.
• Maliyet görünürlüğü — herhangi bir çalıştırmaya --usage ekleyin, ya da kalıcı olarak comrade config set general.show_usage true yapın; her çalıştırma sonunda token/maliyet özeti yazılır. Not: openai_compat OpenAI dışı bir uç noktaya (Qwen, Groq, OpenRouter, yerel bir gateway…) işaret ediyorsa maliyet tahmini gösterilmez — fiyat tablosu yalnızca OpenAI'ın kendi barındırdığı modeli kapsar, ve emin görünen ama yanlış bir rakam hiç göstermemekten daha kötü olurdu. Token sayıları her durumda yazılmaya devam eder.
• comrade doctor — salt-okunur, uçtan uca bir öz-tanı; --live ile gerçek bir doğrulanmış istek gönderir (bir token harcar).
• comrade upgrade — yeni bir sürümü kontrol eder/kurar; --check sadece rapor verir, kurmaz. Yalnızca resmi paket kanallarından kurulmuş sürümlerde çalışır (kaynaktan go build ile yapılan yerel derlemelerde değil). npm (veya aynı dağıtımı kullanan pnpm/yarn/bun) ile kurduysanız kendi kendini güncellemeyi reddeder — bunun yerine o paket yöneticisiyle güncelleyin (--check bu durumda reddetmez).

// 07

Güvenlik, sade anlatım

• Her üretilen komut bir risk sınıfına etiketlenir: read (okuma) < write (yazma) < network (ağ) < elevated (sudo/admin) < destructive (geri alınamaz silme/format). comrade'in kendi yerel kural motoru bu etikete asla körü körüne güvenmez — sadece YÜKSELTEBİLİR, asla düşüremez.
• elevated ve destructive adımlar her modda onay ister — auto modda bile. Bu, safety.confirm_destructive=false/safety.confirm_elevated=false ve --yolo birlikte olmadıkça değişmez; o zaman bile her kullanımda kırmızı bir uyarı basılır.
• Sabit bir kara liste (denylist) vardır: rm -rf /, mkfs, dd of=/dev/..., diskpart clean, drive-root Remove-Item -Recurse ve fork bomb gibi kalıplar hiçbir modda, hiçbir bayrakla çalışmaz — engellenir.
• Tam güvenlik modeli: docs/SECURITY.md.

// 08

Shell entegrasyonu ve öneriler

comrade init [bash|zsh|fish|powershell] (argümansız çağrılırsa $SHELL'den otomatik algılar) hem fix'in ihtiyaç duyduğu kancayı hem de Tab-tamamlamayı tek seferde kurar. Kurulumdan sonra yeni bir terminal açın — değişiklik mevcut oturuma değil, yeni açılan kabuklara uygulanır.

comrade yazıp bir boşluk bıraktığınızda öneriler nasıl görünür, shell'e göre değişir:

// 09

Dosyalar nerede duruyor?

Bir sorunla karşılaşırsanız (Ollama bağlanmıyor, hayalet ipucu çıkmıyor, PATH bulunamıyor, checksum hatası vb.): docs/TROUBLESHOOTING.md.