Terminal üzerinden Cursor ile çalışma: Kapsamlı CLI rehberi

Cursor CLI, grafik arayüzü açmadan doğrudan komut satırından düzenleyiciyi yönetmenize, AI ajanlarını çağırmanıza ve kod refaktörleme işlemleri gerçekleştirmenize olanak tanır. Kurulum için npm install -g @cursor/cli komutunu kullanın (veya ikili dosyayı resmi web sitesinden indirin) ve çalışıp çalışmadığını kontrol etmek için cursor --version yazın. Bu, CI/CD işlem hatlarının yapılandırılmasında ve rutin geliştirme görevlerinin otomasyonunda zaman kazandırır.

Ortamın kurulması ve yapılandırılması

Cursor CLI, mevcut Node.js ekosistemiyle entegre olur veya bağımsız bir ikili dosya olarak dağıtılır. Kurulum yönteminin seçimi, işletim sisteminize ve paket yönetimi tercihlerinize bağlıdır.

Sistem gereksinimleri

• İşletim Sistemi: Windows 10/11 (PowerShell veya WSL2 önerilir), macOS 12+, Linux (Ubuntu 20.04+).
• Bağımlılıklar: Node.js sürüm 18 veya üzeri (npm ile kurulum yapılıyorsa).
• Erişim: API isteklerinin yetkilendirilmesi için aktif bir Cursor hesabı.

Kurulum yöntemleri

1. npm aracılığıyla (evrensel yöntem) Eğer zaten Node.js yüklüyse, bu en hızlı yöntemdir:

npm install -g @cursor/cli

2. Homebrew aracılığıyla (macOS ve Linux için) Diğer yazılımlarla birlikte otomatik güncelleme yapmak için uygundur:

brew install cursor-cli

3. İkili dosya ile kurulum (Windows/Linux) Resmi depodan sürüm arşivini indirin, çıkarın ve yürütülebilir dosyanın yolunu sistem değişkeni PATH içine ekleyin.

Yetkilendirme

AI özelliklerini kullanabilmek için CLI'yi hesabınızla ilişkilendirmeniz gerekir:

cursor login

Bu komut, erişimi onaylamak için bir tarayıcı penceresi açar. Başarılı girişten sonra token yerel yapılandırmaya kaydedilir.

Aracın güncellenmesi

Cursor sık sık yeni modeller eklediği ve ajan mantığını iyileştirdiği için düzenli güncelleme önemlidir.

• npm için:

    npm update -g @cursor/cli
    ```
*   **Homebrew için:**
    
```bash
    brew upgrade cursor-cli
    ```
*   **Sürüm kontrolü:**
    
```bash
    cursor --version
    ```

Güncellemeden sonra bağımlılık hataları oluşursa, npm önbelleğini temizlemeniz (`npm cache clean --force`) ve paketi yeniden kurmanız önerilir.

## Temel komutlar ve sözdizimi

CLI, eylem fiilleri etrafında inşa edilmiştir. Temel komut yapısı şöyledir: `cursor [eylem] [argümanlar] [bayraklar]`.

### Proje ve dosya yönetimi

<div class="table-container"><table style="border-collapse: collapse; width: 100%; margin: 16px 0;"><thead><tr><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Komut</th><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Açıklama</th><th style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; background: #f9fafb; font-weight: 600;">Kullanım örneği</th></tr></thead><tbody><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor init</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Mevcut klasörde <code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">.cursorrules</code> yapılandırmasını başlatır.</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor init</code></td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor open</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Mevcut dizini veya dosyayı Cursor düzenleyicisinde açar.</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor open ./src/app.ts</code></td></tr><tr><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor status</code></td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;">Proje indeksleme durumunu ve tokenları kontrol eder.</td><td style="border: 1px solid #e5e7eb; padding: 8px; text-align: left; vertical-align: top;"><code style="background-color: rgba(0,0,0,0.05); padding: 2px 4px; border-radius: 3px; font-family: monospace; font-size: 0.9em;">cursor status</code></td></tr></tbody></table></div>


### AI ajanları ile çalışma (Composer)

CLI'nin en büyük gücü, GUI'yi açmadan kod üretimi ve refaktörleme işlemlerini çalıştırabilmesidir.

*   **Prompt ile ajan başlatma:**
    
```bash
    cursor compose "src/api klasöründeki tüm API rotalarına hata işleme ekle"
    ```
*   **Sohbet modu (dosyaları değiştirmeden):**
    
```bash
    cursor chat "main.go fonksiyonunun nasıl çalıştığını açıkla"
    ```
*   **Diff'leri (yamaları) uygulama:**
    Ajan değişiklikler önerdiğinde, bunları bayraklar veya etkileşimli menü aracılığıyla kabul edebilir veya reddedebilirsiniz.

### Yapılandırma

Ayarlar `~/.cursor/config.json` dosyasında veya proje düzeyinde yerel olarak saklanır.

*   **Ayarları görüntüleme:**
    
```bash
    cursor config get model
    ```
*   **Varsayılan modeli değiştirme:**
    
```bash
    cursor config set model claude-3.5-sonnet
    ```
*   **Kuralları yönetme (.cursorrules):**
    Belirli bir oturum için dinamik olarak kurallar ekleyebilirsiniz:
    
```bash
    cursor rules add "Her zaman yorumları Türkçe yaz"
    ```

## Cursor CLI ile çalışırken sık karşılaşılan hatalar

1.  **Yetkilendirme hatası (401 Unauthorized)**
    *   *Neden:* Token'ın süresi dolmuş veya iptal edilmiş.
    *   *Çözüm:* `cursor logout` komutunu çalıştırın, ardından tekrar `cursor login` yapın.

2.  **Komut bulunamadı (command not found)**
    *   *Neden:* Global npm paketlerinin yolu PATH'e eklenmemiş.
    *   *Çözüm:* Shell'inizin (.zshrc veya .bashrc) PATH değişkenine `$(npm bin -g)` ekleyin.

3.  **Ajanın bağlamı görmezden gelmesi**
    *   *Neden:* Dosyalar indekslenmemiş veya `.gitignore` / `.cursorignore` aracılığıyla hariç tutulmuş.
    *   *Çözüm:* `.cursorignore` dosyasını kontrol edin ve gerekli dizinlerin engellenmediğinden emin olun. Dosyaları zorla eklemek için `--include` bayrağını kullanın.

4.  **Node.js sürüm çakışmaları**
    *   *Neden:* Eski bir Node.js sürümünün (18'den düşük) kullanılması.
    *   *Çözüm:* Node.js'i nvm veya resmi yükleyici aracılığıyla güncelleyin.

## SSS

**Cursor CLI'yi CI/CD işlem hatlarında kullanabilir miyim?**
Evet, ancak kısıtlamalarla. CLI'yi linting, dokümantasyon oluşturma veya statik analiz için kullanabilirsiniz. Ancak etkileşimli özellikler (Composer) API ile kararlı bir bağlantı gerektirir ve otomatik modda token açısından maliyetli olabilir. Headless modunda kimlik doğrulama için servis API anahtarlarını kullanın.

**Belirli bir görev için bağlam nasıl belirlenir?**
`--file` bayrağını kullanın veya dosya yollarını doğrudan prompt içinde belirtin. Örneğin: `cursor compose "Refaktörleme" --file ./src/utils.js --file ./src/helpers.js`.

**Terminaldeki sohbet geçmişi nerede saklanır?**
Komut geçmişi Cursor'un yerel veritabanında saklanır. Ayarlar > Sohbet Geçmişi bölümünden GUI aracılığıyla buna erişebilirsiniz, ancak CLI'den doğrudan dışa aktarma şu anda dosyaya günlük kaydetme işleviyle (`--log` bayrağı) sınırlıdır.

**API anahtarlarını yapılandırma dosyasında saklamak güvenli midir?**
Hayır. Gizli anahtarları asla `config.json` içinde açık metin olarak saklamayın. Ortam değişkenlerini (örneğin `CURSOR_API_KEY`) veya gizlilik yöneticilerini (Vault, AWS Secrets Manager) kullanın ve bunları çalışma ortamına aktarın.