Bir CLI uzantısı oluşturun

hf CLI, topluluk tarafından sağlanan ve CLI ile sorunsuz 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 uzantılarından ilham almıştır. Bu kılavuzda, kendi uzantınızı nasıl oluşturacağınızı, yayımlayacağınızı ve keşfedilebilir hale getireceğinizi öğreneceksiniz.

Eklentilerin yüklenmesi ve yönetilmesine yönelik kullanıcıya yönelik belgeler için hf extensions CLI referansına 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 izole bir sanal ortamda kurulur.

Her iki tür de aynı kuralları paylaşır:

• GitHub deposu mutlaka hf-<name> (ör. hf-claude, hf-mem) adında olmalıdır.
• Kurulum tamamlandıktan sonra, kullanıcılar eklentiyi hf <name> (ö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-<name> komutunu çalıştırdığında, sistem önce depo kökünde hf-<name> 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-<name> adında çalıştırılabilir bir dosya içeren bir GitHub deposuna ihtiyacınız vardır.

Shell script uzantıları Windows'ta desteklenmez. Uzantınızın Windows'ta çalışması gerekiyorsa, bunun yerine bir Python uzantısı yapın.

Minimal örnek

GitHub'da hf-hello adında, tek dosyalı bir depo oluşturun:

hf-hello (depo kökünde):

#!/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:

>>> hf extensions install <your-username>/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).
• Harici bağımlılıklar (ör. fzf, jq vb.) eklentinizle otomatik olarak kurulmaz. Betiğinizin başlangıcında gerekli araçları kontrol edin ve eksiklerse yardımcı bir hata mesajıyla zarifçe başarısız olun.

Gerçek dünya örneği için 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:

[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.backends._legacy:_Backend"

[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:

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-<name> adını taşımalıdır (burada hf-hello). hf CLI, uzantınızı bu şekilde keşfeder ve çalıştırır.

Kullanıcılar onu aynı şekilde kurar ve çalıştırır:

>>> hf extensions install <your-username>/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-<name>/venv/ konumunda oluşturulur.
2. Paketiniz, GitHub depo arşivinden pip install ile yüklenir.
3. Sistem, venv içinde hf-<name> 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.

Gerçek dünya örneği için 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:

{
    "description": "A short description of what your extension does"
}

2. pyproject.toml description alanı (Python eklentileri için):

[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 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) yazısının yanındaki dişli simgesine tıklayın.
3. “Konular” altında hf-extension ekleyin.

Bu, hf-extension konu sayfası ü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:

>>> 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 <repo> komutuyla listelenen herhangi bir eklentiyi kurabilir.

Eklentinizi test edin

Geliştirme sırasında eklentinizi doğrudan GitHub depodan yükleyebilirsiniz:

# Install from your repo
>>> hf extensions install <your-username>/hf-<name>

# Run it
>>> hf <name>

# Reinstall after making changes (push to GitHub first)
>>> hf extensions install <your-username>/hf-<name> --force

# Update to the latest version (only if a newer commit is available)
>>> hf extensions update <name>

# List installed extensions
>>> hf extensions list

# Remove when done
>>> hf extensions remove <name>

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:

# Update a single extension (accepts `<name>`, `hf-<name>` or `OWNER/hf-<name>`)
>>> 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 bulunmadığında LATEST sütunu kontrol edilir ve eski bir eklenti çalıştırıldığında, hf extensions update <name> 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 <name> sanal ortamını yeniden oluşturur.

Adlandırma kuralları

Eklenti adları şu kurallara uymalıdır:

• GitHub deposunun adı hf-<name> olmalıdır.
• <name> bir harf veya rakamla başlamalıdır.
• <name> harfler, rakamlar, ., _ ve - içerebilir.
• <name>, yerleşik bir hf komutuyla (ör. download, upload, auth) çakışamaz.

Kurulum sırasında kullanıcılar tam OWNER/hf-<name> adını veya yalnızca hf-<name> 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: