# CLI

> biticaret CLI'ı kurmak, tema ve uygulama başlatmak, giriş yapmak, uygulamayı yüklemek ve kodlama asistanlarına MCP sunucusu vermek.

`biticaret` CLI temaları ve uygulamaları başlatır, denetler, derler ve yükler.

## Kurulum

Şimdilik CLI kaynağından derlenir (Go gerekir):

```bash
cd cli
go build -o biticaret ./cmd/biticaret
```

## Tema başlatmak

```bash
biticaret theme init my-theme
```

`./my-theme` klasörünü (ad verilmezse `./skeleton-theme`) Biticaret'in iskelet temasından yazar: her sayfa türü sade bir işaretleme ve biraz CSS ile, MIT lisanslı, yapay zekâ ajanları için bir `AGENTS.md` ile. Tema CLI sürümünün etiketinden (`v<sürüm>`) klonlanır; `--clone-url <git adresi>` başka bir deponun varsayılan dalını klonlar. Dolu bir klasör reddedilir, `--force` içine yazar.

Sonra `biticaret theme check` çalıştırın, tema klasörlerini ZIP yapın ve yönetim panelinde **Online mağaza > Temalar** altından yükleyin.

## Temayı denetlemek ve taşımak

```bash
biticaret theme check my-theme [--strict] [--json]
biticaret theme convert their-theme [--out <klasör>] [--dry-run] [--json] [--report <dosya>]
```

- `theme check`: bir tema klasöründe veya ZIP'te yüklemenin denetimlerini çalıştırır. `--strict` uyarıları da hata sayar; `--json` raporu JSON verir.
- `theme convert`: başka bir platform için yazılmış bir temadaki adları Biticaret adlarına çevirir ve Biticaret'te olmayan çağrıları çıkarır; yerinde ya da `--out` ile boş veya yeni bir klasöre yazar ve her değişikliği raporlar. `--dry-run` hiçbir şey yazmadan raporlar, `--report` JSON raporu bir dosyaya da yazar. Raporda her değişiklik dosyası ve satırıyla yazılır; kalan sorunları `theme check` gösterir.

## Uygulama başlatmak

```bash
biticaret app init my-app
biticaret app init my-blocks --template theme-blocks
```

`./my-app` klasörünü bir başlangıç projesinden yazar: varsayılan olarak uygulama SDK'sı üzerinde küçük bir Go uygulaması (OAuth ile kurulum, KVKK webhook'ları, App Bridge ile yönetim panelinde bir sayfa), ya da `--template` ile bir örnek uygulama: `theme-blocks`, `functions` veya `ui-extensions`. `--clone-url <git adresi>` başka bir deponun varsayılan dalını klonlar; dolu bir klasör reddedilir, `--force` içine yazar. Ardından yeni klasörde `app check` çalıştırır ve sonraki adımları yazar.

## Giriş yapmak

```bash
biticaret auth login [--platform <yönetim paneli adresi>] [--no-browser]
biticaret auth status
biticaret auth logout [--org <id|ad>] [--all]
```

`auth login` bir kod gösterir ve iş ortağı portalının onay sayfasını açar; organizasyonunuzda uygulamalar üzerinde çalışan bir üye orada onaylar. Giriş onaylayan üyenin organizasyonuna bağlıdır; CLI her organizasyon için bir giriş tutar. Jetonlar sistemin anahtar zincirinde saklanır ve CLI onları hiç yazdırmaz. `auth status` girişleri organizasyon, e-posta, rol ve bitiş zamanıyla listeler. `--no-browser` onay sayfasını açmaz, yalnızca adresini yazar. Platform `--platform`, yoksa `$BITICARET_PLATFORM`, yoksa `https://admin.biticaret.com.tr` olur; uygulama komutları son girişin platformunu kullanır.

## Uygulamayla çalışmak

```bash
biticaret app check [klasör] [--config <ortam>] [--json]
biticaret app build [klasör] [--config <ortam>] [--out <klasör>] [--skip-build]
biticaret app generate extension --type function --name tier-discount
biticaret app config use staging
biticaret app config link [--client-id <id> | --name <ad> [--handle <handle>]] [--org <id|ad>] [--force]
biticaret app deploy [--version <ad>] [--message <değişiklikler>] [--submit] [--skip-build] [--org <id|ad>] [--json]
biticaret app versions list [--org <id|ad>] [--json]
```

Klasör verilmezse komut bulunduğunuz klasörde çalışır; `--config <ortam>` `biticaret.app.<ortam>.toml` dosyasını seçer.

- `app check`: yapılandırma dosyalarından manifesti ve paketi kurar ve yüklemenin platform verisi gerektirmeyen denetimlerini çalıştırır. Her sorunu `dosya:satır: anahtar: ileti` olarak yazar; `--json` JSON verir.
- `app build`: her fonksiyonun `[build] command` komutunu çalıştırır, denetler ve `manifest.json` ile `bundle.zip` dosyalarını `.biticaret/build/` altına (ya da `--out` klasörüne) yazar. `--skip-build` komutları çalıştırmaz, `.wasm` dosyalarını olduğu gibi paketler.
- `app generate extension`: `extensions/<ad>/` klasörünü türün şablonundan yazar.
- `app config use <ortam>`: `--config` verilmeden çalışan komutların `biticaret.app.<ortam>.toml` dosyasını kullanmasını sağlar.
- `app config link`: organizasyonunuzun uygulamalarından birini seçer veya yeni bir uygulama oluşturur ve `biticaret.app.toml` dosyasını uygulamanın son sürümünden yazar. `--client-id` sormadan o uygulamayı bağlar, `--name` (ve isteğe bağlı `--handle`) sormadan yeni bir uygulama oluşturur; var olan dosyanın yerine yazmak `--force` ister. Birden çok organizasyonla giriş yaptıysanız yeni bir uygulama için `--org` gerekir (terminalde sorulur).
- `app deploy`: `app build` gibi derler ve denetler, sonra bir taslak sürüm yükler (`--version` verilmezse platform `<handle>-<n>` adını verir); `--submit` sürümü incelemeye gönderir. Sürümler yalnızca bu komutla oluşur: iş ortağı portalının **Sürümler** sekmesi onları listeler ve taslağı incelemeye gönderir, sürüm yüklemez.
- `app versions list`: uygulamanın sürümlerini, en yenisi önce, inceleme durumlarıyla listeler.

Uygulama komutları dosyadaki `client_id` değerinin organizasyonuna ait girişi kullanır; `--org` başkasını seçer. `check`, `build`, `generate` ve `config use` çevrimdışı çalışır; `config link`, `deploy` ve `versions list` için `auth login` gerekir. `.biticaret/` klasörünü git dışında tutun.

## Mağazanın temalarını listelemek

```bash
biticaret theme list --store <mağaza handle> [--platform <yönetim paneli adresi>] [--org <id|ad>] [--json]
```

Organizasyonunuzun bir geliştirme mağazasındaki temaları listeler: kimlik (önizleme bağlantısının `?preview_theme_id=` değeri), ad, yayında olup olmadığı (`published` veya `unpublished`) ve önizleme bağlantısı. `--json` aynı bilgileri `updated_at` ile birlikte JSON olarak verir. `auth login` gerekir; komut mağazaya sahip organizasyonun girişini kullanır, `--org` başkasını seçer. Yalnızca geliştirme mağazaları listelenir: müşteriye devredilecek bir mağaza, başka bir organizasyonun mağazası ve olmayan bir handle aynı "bulunamadı" hatasını verir.

## Yapay zekâ kodlama asistanıyla çalışmak

```bash
biticaret mcp
```

Claude Code, Cursor gibi kodlama asistanları için stdio üzerinden bir MCP sunucusu çalıştırır. Sunucuyu asistan kendisi başlatır; siz yalnızca projenin `.mcp.json` (Claude Code) veya `.cursor/mcp.json` (Cursor) dosyasına eklersiniz:

```json
{
  "mcpServers": {
    "biticaret": {
      "command": "biticaret",
      "args": ["mcp"]
    }
  }
}
```

Claude Code'da `claude mcp add biticaret -- biticaret mcp` de aynı işi görür. `biticaret` PATH üzerinde olmalıdır; değilse `command` olarak tam yolunu verin. Asistan sunucuyu projenin klasöründe başlatır ve araçların varsayılan `dir` değeri o klasördür.

Araçlar yalnızca okur ve denetler: projeye yazmaz, fonksiyonların `[build] command` komutunu çalıştırmaz, girişlerinizi okumaz ve platformu çağırmaz. Yani asistan bu sunucu üzerinden yükleme yapamaz, mağazayı değiştiremez; `app deploy` sizin çalıştırdığınız bir komut olarak kalır.

| Araç | Ne verir |
| :--- | :--- |
| `docs_search` | Bu belgelerin `query` ile en çok eşleşen sayfaları (`limit`, varsayılan 5, en çok 20); sorgu yoksa bütün sayfalar. |
| `docs_read` | Bir sayfanın (`page`) Markdown metni. |
| `config_schema` | `biticaret.app.toml` ve her uzantı türünün `biticaret.extension.toml` anahtarları, türleriyle (`file`: `app`, `theme`, `function`, `ui_extension`, `web_pixel`). |
| `manifest_schema` | `manifest.json` dosyasının her alanı, türüyle. |
| `reference_lists` | Uygulamanın kullanabileceği adlar: izinler, webhook konuları, uzantı hedefleri, fonksiyon ve uzantı türleri; temanın Liquid filtreleri, etiketleri, genel adları ve nesneleri (`list` ile biri seçilir). |
| `app_api_routes` | Uygulama API'sinin yolları: yöntem, yol, gereken izin ve sayfalı olup olmadığı (`scope` ile o izni gerektirenler). |
| `theme_check` | `theme check --json` raporu (`dir`, `strict`). |
| `app_check` | `app check --json` sonucu (`dir`, `config`). |
| `liquid_render` | Temanın bir şablonunu (`template`) düzeniyle ya da bir Liquid parçasını (`source`) örnek bir mağazayla işler; çıktıyı, işlemeden önce bulunan Liquid sorunlarını ve varsa işleme hatasını verir. Hiçbir şey kaydedilmez. |

Belge araçları `https://dev.biticaret.com.tr/llms-full.txt` dosyasını giriş bilgisi göndermeden indirir ve kullanıcı önbellek klasöründe bir gün tutar. Çevrimdışıyken son kopya kullanılır ve sonuç hangi güne ait olduğunu söyler; hiç kopya yoksa belge araçları hata verir, diğerleri çalışır. `BITICARET_DOCS` başka bir kaynak gösterir: bir belge sitesinin adresi veya `llms-full.txt` içeren derlenmiş bir belge klasörü.

`mcp` girdisi kapandığında 0 ile, yanlış kullanımda veya çıktısını yazamadığında 2 ile çıkar; araçların bulduğu sorunlar çıkış kodunda değil, sonuçtadır.

## Çıkış kodları

| Kod | Anlamı |
| :--- | :--- |
| 0 | Tamam: tema veya uygulama denetimden geçti, dosyalar yazıldı veya sürüm yüklendi. |
| 1 | Tema veya uygulamanın düzeltilmesi gerekiyor: denetim hata buldu, platform yüklemeyi veya incelemeye göndermeyi reddetti; `auth status` için giriş yapılmamış. |
| 2 | Yanlış kullanım veya komut çalışamadı: klasör boş değil, klonlama başarısız, dosya zaten var, giriş yapılmamış, platforma ulaşılamıyor veya dosyadaki `client_id` ile bir uygulama yok. |
