Создание расширения CLI

CLI hf поддерживает расширения — пользовательские команды, предоставляемые сообществом и бесшовно интегрируемые в CLI. Расширения размещаются в публичных репозиториях GitHub и устанавливаются одной командой. После установки они отображаются как команды верхнего уровня hf, аналогично встроенным.

Эта система вдохновлена расширениями GitHub CLI. В этом руководстве вы узнаете, как создать собственное расширение, опубликовать его и сделать доступным для поиска.

См. справочник CLI для hf extensions для пользовательской документации по установке и управлению расширениями.

Обзор

Существует два типа расширений:

1. Расширения для shell-скриптов: один исполняемый файл (bash-скрипт, скомпилированный бинарный файл и т. д.), размещённый в корне репозитория.
2. Расширения Python: стандартный пакет Python с файлом pyproject.toml. Устанавливается в изолированную виртуальную среду, чтобы зависимости не конфликтовали с системными.

Оба типа используют одни и те же соглашения:

• Репозиторий GitHub должен называться hf-<name> (например, hf-claude, hf-mem).
• После установки пользователи запускают расширение с помощью hf <name> (например, hf claude).
• Расширение перечислено в hf --help в разделе «Extension commands».

Когда пользователь выполняет hf extensions install [OWNER/]hf-<name>, система сначала ищет файл бинарного/скриптового типа с именем hf-<name> в корне репозитория. Если файл найден, он устанавливается как расширение в виде shell-скрипта. В противном случае система переходит к установке репозитория как Python-пакета.

Создание расширения для shell-скрипта

Расширение на основе shell-скрипта — самый простой тип. Достаточно иметь репозиторий на GitHub с исполняемым файлом с именем hf-<name> в корне.

Расширения на языке Shell не поддерживаются в Windows. Если ваше расширение должно работать в Windows, используйте вместо него расширение на Python.

Минимальный пример

Создайте репозиторий с именем hf-hello на GitHub с одним файлом:

hf-hello (в корне репозитория):

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

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

Всё готово! Теперь пользователи могут установить и запустить его:

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

Советы по расширениям для скриптов оболочки

• Всегда начинайте с shebang (#!/usr/bin/env bash) и set -euo pipefail для безопасности.
• Скрипт получает все дополнительные аргументы, переданные пользователем. Например, hf hello --name world передаёт --name world в скрипт.
• Если пользователь выполнен вошёл в систему, то его токен Hugging Face можно получить через переменную окружения HF_TOKEN.
• Добавьте manifest.json в корень репозитория, чтобы предоставить описание (см. Добавление описания).
• Внешние зависимости (например, fzf, jq и т. д.) не устанавливаются автоматически вместе с вашим расширением. Проверяйте наличие необходимых инструментов в начале скрипта и при их отсутствии корректно завершайте работу с понятным сообщением об ошибке.

В качестве примера из реальной практики см. hanouticelina/hf-claude — расширение для shell-скрипта, которое запускает Claude Code с HF Inference Providers.

Создание расширения Python

Расширения на Python — это полноценные пакеты Python, устанавливаемые в изолированную виртуальную среду. Это лучший вариант, если ваше расширение имеет зависимости на Python или более сложную логику.

Минимальный пример

Создайте репозиторий с именем hf-hello на GitHub со следующей структурой:

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

Критически важной частью является точка входа [project.scripts]: она должна называться hf-<name> (в данном случае hf-hello). Именно так CLI hf находит и выполняет ваше расширение.

Пользователи устанавливают и запускают его так же:

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

Как устанавливаются расширения Python

Когда пользователь устанавливает расширение Python, происходит следующее:

1. Виртуальное окружение создаётся в ~/.local/share/hf/extensions/hf-<name>/venv/.
2. Ваш пакет устанавливается с помощью pip install из архива репозитория GitHub.
3. Система проверяет, что в venv был создан консольный скрипт hf-<name>.

Это означает, что зависимости вашего расширения полностью изолированы — они не будут конфликтовать с другими пакетами Python пользователя.

В качестве примера из реальной практики см. alvarobartt/hf-mem — расширение для Python, которое оценивает требования к памяти при инференсе для моделей HF.

Добавьте описание

Описание помогает пользователям понять, что делает ваше расширение. Оно отображается в hf extensions list и в hf --help.

Система ищет описание в следующем порядке:

1. manifest.json в корне репозитория:

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

2. pyproject.toml поле description (для расширений Python):

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

3. Описание репозитория на GitHub (поле «About» на странице репозитория).

Для расширений на Python наиболее естественным подходом является указание description в pyproject.toml. Для расширений на shell-скриптах используйте файл manifest.json или укажите описание репозитория GitHub.

Сделайте ваше расширение доступным для поиска

Чтобы пользователи могли найти ваше расширение, добавьте тему hf-extension в ваш репозиторий GitHub:

1. Перейдите в ваш репозиторий на GitHub.
2. Нажмите на значок шестерёнки рядом с «About» в правой боковой панели.
3. В разделе «Темы» добавьте hf-extension.

Это общепринятая в сообществе практика, которая упрощает просмотр всех доступных расширений на странице темы hf-extension.

После этого пользователи смогут найти ваше расширение прямо из CLI с помощью hf extensions search, которое выводит список всех репозиториев GitHub с тегом hf-extension, отсортированных по числу звёзд:

>>> 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 показывает, какие расширения уже установлены локально. Оттуда пользователи могут установить любое из перечисленных расширений с помощью hf extensions install <repo>.

Проверьте ваше расширение

В процессе разработки вы можете установить своё расширение непосредственно из вашего репозитория на GitHub:

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

Используйте --force для перезаписи ранее установленной версии при тестировании обновлений.

Обновление установленных расширений

После установки расширения вы можете обновить его до последней версии, опубликованной на 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 обновляет только уже установленные расширения. Если расширение не установлено, возникает ошибка. Расширения, которые уже актуальны, пропускаются.

Версия расширения — это коммит, из которого оно было установлено, отображаемый в виде короткого SHA в столбце VERSION команды hf extensions list. Столбец LATEST проверяется, когда на GitHub недоступен более новый коммит, а при запуске устаревшего расширения выводится подсказка с предложением выполнить hf extensions update <name>. Чтобы не превышать лимиты GitHub для неавторизованных запросов, hf запрашивает последний коммит каждого расширения не чаще одного раза в день. Чтобы отключить эти проверки, установите HF_HUB_DISABLE_UPDATE_CHECK=1.

Если расширение Python перестаёт работать, потому что интерпретатор Python, с которым оно было установлено, был удалён (например, после обновления Homebrew), hf extensions update <name> пересоздаёт его виртуальное окружение.

Правила именования

Имена расширений должны соответствовать следующим правилам:

• Репозиторий GitHub должен называться hf-<name>.
• <name> должен начинаться с буквы или цифры.
• <name> может содержать буквы, цифры, ., _ и -.
• <name> не может конфликтовать с встроенной командой hf (например, download, upload, auth).

При установке пользователь может указать полное имя OWNER/hf-<name> или только hf-<name> (по умолчанию используется организация huggingface).

Существующие расширения

Вот несколько расширений сообщества, которые можно использовать в качестве примера: