# Bir CLI uzantısı oluşturun `hf` CLI, topluluk tarafından sağlanan ve CLI'ye kusursuz bir şekilde entegre olan eklentileri ve özel komutları destekler. Eklentiler, herkese açık GitHub depoları olarak barındırılır ve tek bir komutla yüklenebilir. Yüklendikten sonra, yerleşik komutlar gibi üst düzey `hf` komutları olarak görünürler. Bu sistem, [GitHub CLI eklentileri](https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions)'nden ilham alınarak tasarlanmıştır. Bu kılavuzda kendi eklentinizi nasıl oluşturacağınızı, yayımlayacağınızı ve keşfedilebilir hale getireceğinizi öğreneceksiniz. > [!TIP] > Eklentilerin yüklenmesi ve yönetilmesine yönelik kullanıcıya yönelik belgeler için [`hf extensions` CLI referansına](../package_reference/cli#hf-extensions) bakın. ## Genel Bakış İki tür uzantı vardır: 1. **Shell betiği uzantıları**: depoyun kök dizinine yerleştirilen tek bir çalıştırılabilir dosya (bash betiği, derlenmiş ikili vb.). 2. **Python eklentileri**: `pyproject.toml` içeren standart bir Python paketi. Bağımlılıkların kullanıcının sistemiyle çakışmaması için yalıtılmış bir sanal ortamda kurulur. Her iki tür de aynı kuralları paylaşır: - GitHub deposu **mutlaka** `hf-` (ör. `hf-claude`, `hf-mem`) adında olmalıdır. - Kurulum tamamlandıktan sonra, kullanıcılar eklentiyi `hf ` (ör. `hf claude`) ile çalıştırır. - Eklenti, `hf --help` çıktısında "Extension commands" başlığı altında listelenir. Bir kullanıcı `hf extensions install [OWNER/]hf-` komutunu çalıştırdığında, sistem önce depo kökünde `hf-` adında bir binary/script dosyası arar. Bulunursa, bir shell script eklentisi olarak yüklenir. Aksi takdirde, depo bir Python paketi olarak yüklenir. ## Bir kabuk betiği uzantısı oluşturun Bir kabuk betiği uzantısı en basit türdür. Kök dizinde `hf-` adında çalıştırılabilir bir dosya içeren bir GitHub deposuna ihtiyacınız vardır. > [!WARNING] > Shell script uzantıları Windows'ta desteklenmez. Uzantınızın Windows'ta çalışması gerekiyorsa, bunun yerine bir [Python uzantısı](#create-a-python-extension) yapın. ### Minimal örnek GitHub'da `hf-hello` adında, tek dosyalı bir depo oluşturun: **`hf-hello`** (depo kökünde): ```bash #!/usr/bin/env bash set -euo pipefail echo "Hello from hf-hello extension!" echo "Arguments: $@" ``` Bitti! Kullanıcılar artık bunu kurup çalıştırabilir: ```bash >>> hf extensions install /hf-hello >>> hf hello Hello from hf-hello extension! Arguments: ``` ### Kabuk betiği uzantıları için ipuçları - Her zaman bir shebang (`#!/usr/bin/env bash`) ile başlayın ve güvenlik için `set -euo pipefail` kullanın. - Betik, kullanıcının ilettiği tüm ek argümanları alır. Örneğin, `hf hello --name world` betiğe `--name world` argümanını iletir. - Kullanıcı giriş yaptıysa, Hugging Face jetonuna `HF_TOKEN` ortam değişkeni üzerinden erişebilirsiniz. - Depo kökünde bir açıklama sağlamak için `manifest.json` ekleyin (bkz. [Açıklama ekleme](#add-a-description)). - Harici bağımlılıklar (ör. `fzf`, `jq` vb.) eklentinizle **otomatik olarak** kurulmaz. Betiğinizin başında gerekli araçları kontrol edin ve eksiklerse yardımcı bir hata mesajıyla zarifçe başarısız olun. > [!TIP] > Gerçek dünya örneği için [hanouticelina/hf-claude](https://github.com/hanouticelina/hf-claude) adresine bakın — HF Inference Providers ile Claude Code'u başlatan bir kabuk betiği uzantısı. ## Bir Python uzantısı oluşturun Python uzantıları, izole bir sanal ortamda kurulan tam Python paketleridir. Uzantınızın Python bağımlılıkları veya daha karmaşık bir mantığı varsa bu en iyi seçenektir. ### Minimal örnek GitHub'da bu yapıya sahip `hf-hello` adında bir depo oluşturun: ``` hf-hello/ ├── pyproject.toml └── src/ └── hf_hello/ ├── __init__.py └── cli.py ``` **`pyproject.toml`**: ```toml [build-system] requires = ["setuptools>=64"] build-backend = "setuptools.build_meta" [project] name = "hf-hello" version = "0.1.0" description = "A hello-world hf CLI extension" requires-python = ">=3.10" [project.scripts] hf-hello = "hf_hello.cli:main" ``` **`src/hf_hello/cli.py`**: ```python import sys def main(): print("Hello from hf-hello extension!") print(f"Arguments: {sys.argv[1:]}") if __name__ == "__main__": main() ``` Kritik kısım, `[project.scripts]` giriş noktasıdır: **mutlaka** `hf-` adını taşımalıdır (burada `hf-hello`). `hf` CLI, uzantınızı keşfetmek ve çalıştırmak için bunu kullanır. Kullanıcılar onu aynı şekilde kurar ve çalıştırır: ```bash >>> hf extensions install /hf-hello >>> hf hello Hello from hf-hello extension! Arguments: [] ``` ### Python eklentilerinin nasıl yüklendiği Bir kullanıcı Python eklentisi yüklediğinde, aşağıdaki olaylar gerçekleşir: 1. Sanal ortam `~/.local/share/hf/extensions/hf-/venv/` konumunda oluşturulur. 2. Paketiniz, GitHub depo arşivinden `pip install` ile yüklenir. 3. Sistem, venv içinde `hf-` konsol betiğinin oluşturulduğunu doğrular. Bu, eklentinizin bağımlılıklarının tamamen izole olduğu anlamına gelir — kullanıcının diğer Python paketleriyle çelişmezler. > [!TIP] > Gerçek dünya örneği için [alvarobartt/hf-mem](https://github.com/alvarobartt/hf-mem) adresine bakın — HF modelleri için çıkarım bellek gereksinimlerini tahmin eden bir Python eklentisi. ## Açıklama ekleyin Açıklama, kullanıcıların uzantınızın ne yaptığını anlamasına yardımcı olur. `hf extensions list` ve `hf --help` çıktılarında görünür. Sistem, bir açıklama için aşağıdaki sırayla arama yapar: 1. Depo kökünde **`manifest.json`**: ```json { "description": "A short description of what your extension does" } ``` 2. **`pyproject.toml`** `description` alanı (Python eklentileri için): ```toml [project] description = "A short description of what your extension does" ``` 3. **GitHub deposu açıklaması** (depo sayfasındaki "About" alanı). Python eklentileri için `pyproject.toml` içinde `description` ayarlamak en doğal yaklaşımdır. Kabuk betiği eklentileri için bir `manifest.json` dosyası kullanın veya GitHub deposu açıklamasını ayarlayın. ## Eklentinizi keşfedilebilir hale getirin Kullanıcıların uzantınızı bulmasına yardımcı olmak için GitHub depomuza **`hf-extension`** konusunu ekleyin: 1. GitHub'daki deponuza gidin. 2. Sağ kenar çubuğundaki "About" (Hakkında) yanındaki dişli simgesine tıklayın. 3. "Konular" altında `hf-extension` ekleyin. Bu, [hf-extension konu sayfası](https://github.com/topics/hf-extension) üzerinden tüm mevcut eklentileri kolayca görüntülemenizi sağlayan bir topluluk konvansiyonudur. Kullanıcılar, `hf extensions search` komutuyla uzantınızı doğrudan CLI üzerinden keşfedebilir; bu komut, `hf-extension` konusu etiketiyle işaretlenmiş tüm GitHub depolarını yıldız sayısına göre sıralayarak listeler: ```bash >>> hf extensions search NAME REPO STARS DESCRIPTION INSTALLED ------ ----------------------- ----- ----------------------------------- --------- claude hanouticelina/hf-claude 2 Extension for `hf` CLI to launch... yes agents hanouticelina/hf-agents HF extension to run local coding... ``` `INSTALLED` sütunu, yerel olarak zaten kurulu olan eklentileri gösterir. Kullanıcılar, oradan `hf extensions install ` komutuyla listedeki herhangi bir eklentiyi kurabilir. ## Eklentinizi test edin Geliştirme sırasında eklentinizi doğrudan GitHub depodan yükleyebilirsiniz: ```bash # Install from your repo >>> hf extensions install /hf- # Run it >>> hf # Reinstall after making changes (push to GitHub first) >>> hf extensions install /hf- --force # Update to the latest version (only if a newer commit is available) >>> hf extensions update # List installed extensions >>> hf extensions list # Remove when done >>> hf extensions remove ``` > [!TIP] > Güncellemeleri test ederken daha önce yüklenmiş bir sürümün üzerine yazmak için `--force` kullanın. ## Yüklü eklentileri güncelle Bir eklenti yüklendikten sonra, GitHub'da yayınlanan en son sürüme güncelleyebilirsiniz: ```bash # Update a single extension (accepts ``, `hf-` or `OWNER/hf-`) >>> hf extensions update hf-claude # Check every installed extension and update the outdated ones >>> hf extensions update ``` `hf extensions update`, yalnızca zaten yüklü olan eklentileri günceller. Eklenti yüklü değilse bir hata oluşturulur. Güncel olan eklentiler atlanır. Bir eklentinin sürümü, yüklendiği commit'tir ve `hf extensions list` komutundaki `VERSION` sütununda kısa bir SHA olarak gösterilir. GitHub üzerinde daha yeni bir commit mevcut değilse `LATEST` sütunu kontrol edilir ve eski bir eklenti çalıştırıldığında, `hf extensions update ` komutunu öneren bir ipucu yazdırılır. Kimlik doğrulaması yapılmamış istekler için GitHub'ın hız sınırları içinde kalmak amacıyla, `hf` her eklentinin en son commit'ini günde en fazla bir kez sorgular. Bu kontrolleri devre dışı bırakmak için `HF_HUB_DISABLE_UPDATE_CHECK=1` değerini ayarlayın. Bir Python uzantısı, yüklendiği Python sürümü kaldırıldığında (ör. bir Homebrew yükseltmesinden sonra) çalışmayı durdurursa, `hf extensions update ` sanal ortamını yeniden oluşturur. ## Adlandırma kuralları Eklenti adları şu kurallara uymalıdır: - GitHub deposunun adı `hf-` olmalıdır. - `` bir harf veya rakamla başlamalıdır. - `` harfler, rakamlar, `.`, `_` ve `-` içerebilir. - ``, yerleşik bir `hf` komutuyla (ör. `download`, `upload`, `auth`) çakışamaz. Kurulum sırasında kullanıcılar, tam `OWNER/hf-` adını veya yalnızca `hf-` adını (varsayılan olarak `huggingface` kuruluşuna işaret eder) belirtebilir. ## Mevcut uzantılar Referans olarak kullanabileceğiniz bazı topluluk uzantıları şunlardır: | Eklenti | Tür | Açıklama | |-----------|------|-------------| | [hanouticelina/hf-claude](https://github.com/hanouticelina/hf-claude) | Kabuk betiği | HF Inference Providers ile Claude Code'u başlatın | | [alvarobartt/hf-mem](https://github.com/alvarobartt/hf-mem) | Python | HF modelleri için çıkarım bellek gereksinimlerini tahmin edin |