Crear una extensión de CLI

La CLI hf admite extensiones, comandos personalizados proporcionados por la comunidad que se integran de forma transparente en la CLI. Las extensiones se alojan en repositorios públicos de GitHub y se pueden instalar con un solo comando. Una vez instaladas, aparecen como comandos de nivel superior de hf, al igual que los integrados.

Este sistema se inspira en las extensiones de GitHub CLI. En esta guía, aprenderás a crear tu propia extensión, publicarla y hacerla descubreble.

Para la documentación orientada al usuario sobre la instalación y gestión de extensiones, consulte la referencia de la CLI para hf extensions.

Resumen

Hay dos tipos de extensiones:

1. Extensiones de scripts de shell: un único archivo ejecutable (script de bash, binario compilado, etc.) situado en la raíz del repositorio.
2. Extensiones de Python: un paquete de Python estándar con un pyproject.toml. Se instala en un entorno virtual aislado para que las dependencias no entren en conflicto con el sistema del usuario.

Ambos tipos comparten las mismas convenciones:

• El repositorio de GitHub debe llamarse hf-<name> (p. ej., hf-claude, hf-mem).
• Una vez instalado, los usuarios ejecutan la extensión con hf <name> (p. ej., hf claude).
• La extensión se lista en hf --help bajo “Extension commands”.

Cuando un usuario ejecuta hf extensions install [OWNER/]hf-<name>, el sistema primero busca un archivo binario o de script llamado hf-<name> en la raíz del repositorio. Si lo encuentra, lo instala como una extensión de script de shell. De lo contrario, recurre a instalar el repositorio como un paquete de Python.

Crear una extensión de script de shell

La extensión de script de shell es el tipo más simple. Solo necesitas un repositorio de GitHub con un archivo ejecutable llamado hf-<name> en la raíz.

Las extensiones de scripts de shell no se admiten en Windows. Si su extensión debe funcionar en Windows, utilice una extensión de Python en su lugar.

Ejemplo mínimo

Crea un repositorio llamado hf-hello en GitHub con un solo archivo:

hf-hello (en la raíz del repositorio):

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

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

¡Eso es todo! Ahora los usuarios pueden instalarlo y ejecutarlo:

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

Consejos para extensiones de scripts de shell

• Comience siempre con un shebang (#!/usr/bin/env bash) y set -euo pipefail para mayor seguridad.
• El script recibe todos los argumentos adicionales que pasa el usuario. Por ejemplo, hf hello --name world pasa --name world al script.
• Puedes acceder al token de Hugging Face del usuario a través de la variable de entorno HF_TOKEN si está conectado.
• Agrega un manifest.json en la raíz del repositorio para proporcionar una descripción (consulta Agregar una descripción).
• Las dependencias externas (p. ej., fzf, jq, etc.) no se instalan automáticamente con tu extensión. Comprueba las herramientas necesarias al inicio de tu script y falla de forma elegante con un mensaje de error útil si faltan.

Para un ejemplo del mundo real, consulte hanouticelina/hf-claude — una extensión de script de shell que lanza Claude Code con HF Inference Providers.

Crear una extensión de Python

Las extensiones de Python son paquetes Python completos instalados en un entorno virtual aislado. Esta es la mejor opción cuando su extensión tiene dependencias de Python o una lógica más compleja.

Ejemplo mínimo

Crea un repositorio llamado hf-hello en GitHub con esta estructura:

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

La parte crítica es el punto de entrada [project.scripts]: debe llamarse hf-<name> (en este caso, hf-hello). Así es como la CLI hf descubre y ejecuta tu extensión.

Los usuarios lo instalan y lo ejecutan de la misma manera:

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

Cómo se instalan las extensiones de Python

Cuando un usuario instala una extensión de Python, ocurre lo siguiente:

1. Se crea un entorno virtual en ~/.local/share/hf/extensions/hf-<name>/venv/.
2. Su paquete se instala mediante pip install desde el archivo del repositorio de GitHub.
3. El sistema verifica que se haya creado un script de consola hf-<name> en el venv.

Esto significa que las dependencias de su extensión están completamente aisladas: no entrarán en conflicto con otros paquetes de Python del usuario.

Para un ejemplo del mundo real, consulte alvarobartt/hf-mem — una extensión de Python que estima los requisitos de memoria de inferencia para modelos de HF.

Agrega una descripción

La descripción ayuda a los usuarios a entender qué hace tu extensión. Aparece en hf extensions list y en hf --help.

El sistema busca una descripción en el siguiente orden:

1. manifest.json en la raíz del repositorio:

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

2. Campo description de pyproject.toml (para extensiones de Python):

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

3. Descripción del repositorio de GitHub (el campo “About” en la página del repositorio).

Para las extensiones de Python, la forma más natural es establecer description en pyproject.toml. Para las extensiones de scripts de shell, use un archivo manifest.json o establezca la descripción del repositorio de GitHub.

Haz que tu extensión sea descubreble

Para ayudar a los usuarios a encontrar tu extensión, añade el tema hf-extension a tu repositorio de GitHub:

1. Vaya a su repositorio en GitHub.
2. Haz clic en el icono de engranaje junto a “About” en la barra lateral derecha.
3. En “Topics”, añade hf-extension.

Esta es una convención de la comunidad que facilita la consulta de todas las extensiones disponibles en la página del tema hf-extension.

Los usuarios pueden descubrir su extensión directamente desde la CLI con hf extensions search, que lista todos los repositorios de GitHub etiquetados con el tema hf-extension, ordenados por estrellas:

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

La columna INSTALLED muestra qué extensiones ya están instaladas localmente. Desde ahí, los usuarios pueden instalar cualquier extensión de la lista con hf extensions install <repo>.

Prueba tu extensión

Durante el desarrollo, puedes instalar tu extensión directamente desde tu repositorio de 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>

Use --force para sobrescribir una versión previamente instalada al probar actualizaciones.

Actualizar las extensiones instaladas

Una vez que se instala una extensión, puedes actualizarla a la última versión publicada en 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 solo actualiza las extensiones que ya están instaladas. Si la extensión no está instalada, se genera un error. Las extensiones que ya están actualizadas se omiten.

La versión de una extensión es el commit desde el que se instaló, mostrado como un SHA corto en la columna VERSION de hf extensions list. La columna LATEST se comprueba cuando no hay un commit más nuevo disponible en GitHub, y ejecutar una extensión desactualizada imprime una sugerencia que indica hf extensions update <name>. Para mantenerse dentro de los límites de tasa de GitHub para solicitudes no autenticadas, hf consulta el commit más reciente de cada extensión como máximo una vez al día. Establece HF_HUB_DISABLE_UPDATE_CHECK=1 para deshabilitar estas comprobaciones.

Si una extensión de Python deja de funcionar porque se eliminó la versión de Python con la que se instaló (por ejemplo, tras una actualización de Homebrew), hf extensions update <name> vuelve a crear su entorno virtual.

Reglas de nomenclatura

Los nombres de las extensiones deben seguir estas reglas:

• El repositorio de GitHub debe llamarse hf-<name>.
• <name> debe comenzar con una letra o un dígito.
• <name> puede contener letras, dígitos, ., _ y -.
• <name> no puede entrar en conflicto con un comando integrado de hf (p. ej., download, upload, auth).

Al instalar, los usuarios pueden especificar el OWNER/hf-<name> completo o solo hf-<name> (que por defecto corresponde a la organización huggingface).

Extensiones existentes

Aquí hay algunas extensiones de la comunidad que puedes usar como referencia: