Buat ekstensi CLI

CLI hf mendukung ekstensi, yaitu perintah kustom yang disediakan oleh komunitas dan terintegrasi secara mulus ke dalam CLI. Ekstensi dihosting sebagai repositori GitHub publik dan dapat diinstal dengan satu perintah. Setelah diinstal, ekstensi muncul sebagai perintah tingkat atas hf persis seperti perintah bawaan.

Sistem ini terinspirasi oleh ekstensi GitHub CLI. Dalam panduan ini, Anda akan belajar cara membuat ekstensi Anda sendiri, menerbitkannya, dan membuatnya dapat ditemukan.

Untuk dokumentasi yang ditujukan pengguna mengenai instalasi dan pengelolaan ekstensi, lihat referensi CLI untuk hf extensions.

Ikhtisar

Ada dua jenis ekstensi:

1. Ekstensi skrip shell: satu file yang dapat dieksekusi (skrip bash, biner terkompilasi, dll.) yang ditempatkan di akar repositori.
2. Ekstensi Python: paket Python standar dengan pyproject.toml. Diinstal di lingkungan virtual yang terisolasi agar dependensi tidak bentrok dengan sistem pengguna.

Kedua tipe berbagi konvensi yang sama:

• Repositori GitHub harus diberi nama hf-<name> (misalnya, hf-claude, hf-mem).
• Setelah terinstal, pengguna menjalankan ekstensi dengan hf <name> (misalnya, hf claude).
• Ekstensi tersebut terdaftar di hf --help di bawah “Perintah ekstensi”.

Saat pengguna menjalankan hf extensions install [OWNER/]hf-<name>, sistem pertama kali mencari file biner/skrip bernama hf-<name> di root repositori. Jika ditemukan, file tersebut diinstal sebagai ekstensi skrip shell. Jika tidak, sistem beralih ke instalasi repositori sebagai paket Python.

Buat ekstensi skrip shell

Ekstensi skrip shell adalah tipe yang paling sederhana. Anda hanya perlu sebuah repositori GitHub dengan file yang dapat dieksekusi bernama hf-<name> di root.

Ekstensi skrip shell tidak didukung di Windows. Jika ekstensi Anda harus berfungsi di Windows, buatlah sebagai ekstensi Python sebagai gantinya.

Contoh minimal

Buat repositori bernama hf-hello di GitHub dengan satu file:

hf-hello (di akar repositori):

#!/usr/bin/env bash
set -euo pipefail

echo "Hello from hf-hello extension!"
echo "Arguments: $@"

Itu saja! Pengguna sekarang dapat menginstal dan menjalankannya:

>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments:

Tips untuk ekstensi skrip shell

• Selalu mulai dengan shebang (#!/usr/bin/env bash) dan set -euo pipefail untuk keamanan.
• Skrip menerima semua argumen tambahan yang diteruskan oleh pengguna. Misalnya, hf hello --name world meneruskan --name world ke skrip.
• Anda dapat mengakses token Hugging Face pengguna melalui variabel lingkungan HF_TOKEN jika mereka telah masuk.
• Tambahkan manifest.json di root repositori untuk menyediakan deskripsi (lihat Menambahkan deskripsi).
• Dependensi eksternal (misalnya, fzf, jq, dll.) tidak diinstal secara otomatis bersama ekstensi Anda. Periksa peralatan yang diperlukan di awal skrip Anda dan gagal dengan anggun menggunakan pesan kesalahan yang membantu jika mereka tidak ada.

Untuk contoh dunia nyata, lihat hanouticelina/hf-claude — ekstensi skrip shell yang meluncurkan Claude Code dengan HF Inference Providers.

Buat ekstensi Python

Ekstensi Python adalah paket Python lengkap yang diinstal dalam lingkungan virtual yang terisolasi. Ini adalah pilihan terbaik ketika ekstensi Anda memiliki dependensi Python atau logika yang lebih kompleks.

Contoh minimal

Buat repositori bernama hf-hello di GitHub dengan struktur ini:

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()

Bagian yang krusial adalah titik masuk [project.scripts]: ia harus diberi nama hf-<name> (di sini, hf-hello). Inilah cara CLI hf menemukan dan menjalankan ekstensi Anda.

Pengguna menginstal dan menjalankannya dengan cara yang sama:

>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments: []

Cara ekstensi Python diinstal

Saat pengguna menginstal ekstensi Python, hal berikut terjadi:

1. Lingkungan virtual dibuat di ~/.local/share/hf/extensions/hf-<name>/venv/.
2. Paket Anda diinstal melalui pip install dari arsip repositori GitHub.
3. Sistem memverifikasi bahwa skrip konsol hf-<name> telah dibuat di venv.

Ini berarti dependensi ekstensi Anda terisolasi sepenuhnya — mereka tidak akan bentrok dengan paket Python lain milik pengguna.

Untuk contoh dunia nyata, lihat alvarobartt/hf-mem — ekstensi Python yang memperkirakan kebutuhan memori inferensi untuk model HF.

Tambahkan deskripsi

Deskripsi membantu pengguna memahami apa yang dilakukan ekstensi Anda. Deskripsi ini muncul di hf extensions list dan di hf --help.

Sistem mencari deskripsi dalam urutan berikut:

1. manifest.json di root repositori:

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

2. pyproject.toml description field (untuk ekstensi Python):

[project]
description = "A short description of what your extension does"

3. Deskripsi repositori GitHub (kolom “About” di halaman repositori).

Untuk ekstensi Python, mengatur description di pyproject.toml adalah pendekatan yang paling alami. Untuk ekstensi shell script, gunakan file manifest.json atau atur deskripsi repositori GitHub.

Buat ekstensi Anda dapat ditemukan

Untuk membantu pengguna menemukan ekstensi Anda, tambahkan topik hf-extension ke repositori GitHub Anda:

1. Buka repositori Anda di GitHub.
2. Klik ikon roda gigi di sebelah “About” pada bilah sisi kanan.
3. Di bawah “Topics”, tambahkan hf-extension.

Ini adalah konvensi komunitas yang memudahkan penelusuran semua ekstensi yang tersedia di halaman topik hf-extension.

Pengguna kemudian dapat menemukan ekstensi Anda langsung dari CLI dengan hf extensions search, yang menampilkan semua repositori GitHub yang diberi tag topik hf-extension, diurutkan berdasarkan bintang:

>>> 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...

Kolom INSTALLED menunjukkan ekstensi mana yang sudah terpasang secara lokal. Dari sana, pengguna dapat memasang ekstensi yang terdaftar dengan hf extensions install <repo>.

Uji ekstensi Anda

Selama pengembangan, Anda dapat menginstal ekstensi Anda langsung dari repositori GitHub Anda:

# 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>

Gunakan --force untuk menimpa versi yang sebelumnya terinstal saat menguji pembaruan.

Perbarui ekstensi yang terpasang

Setelah ekstensi diinstal, Anda dapat memperbaruinya ke versi terbaru yang dipublikasikan di GitHub:

# 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 hanya memperbarui ekstensi yang sudah terpasang. Jika ekstensi belum terpasang, error akan dilempar. Ekstensi yang sudah versi terbaru akan dilewati.

Versi ekstensi adalah commit tempat ekstensi tersebut diinstal, yang ditampilkan sebagai SHA pendek di kolom VERSION dari hf extensions list. Kolom LATEST diperiksa ketika tidak ada commit yang lebih baru tersedia di GitHub, dan menjalankan ekstensi yang sudah kedaluwarsa akan menampilkan petunjuk yang menyarankan hf extensions update <name>. Untuk tetap berada dalam batas laju GitHub untuk permintaan yang tidak terautentikasi, hf mencari commit terbaru dari setiap ekstensi paling banyak sekali sehari. Atur HF_HUB_DISABLE_UPDATE_CHECK=1 untuk menonaktifkan pemeriksaan ini.

Jika ekstensi Python berhenti berfungsi karena Python yang digunakan saat instalasinya dihapus (misalnya setelah upgrade Homebrew), hf extensions update <name> akan membuat ulang lingkungan virtualnya.

Aturan penamaan

Nama ekstensi harus mengikuti aturan berikut:

• Repositori GitHub harus diberi nama hf-<name>.
• <name> harus diawali dengan huruf atau angka.
• <name> dapat berisi huruf, angka, ., _, dan -.
• <name> tidak boleh bentrok dengan perintah bawaan hf (misalnya, download, upload, auth).

Saat menginstal, pengguna dapat menentukan OWNER/hf-<name> lengkap atau hanya hf-<name> (yang secara default menggunakan organisasi huggingface).

Ekstensi yang ada

Berikut adalah beberapa ekstensi komunitas yang dapat Anda gunakan sebagai referensi: