Créer une extension CLI

Le CLI hf prend en charge les extensions, des commandes personnalisées fournies par la communauté qui s’intègrent de manière transparente au CLI. Les extensions sont hébergées dans des dépôts GitHub publics et peuvent être installées avec une seule commande. Une fois installées, elles apparaissent comme des commandes de premier niveau de hf, tout comme les commandes intégrées.

Ce système s’inspire des extensions de GitHub CLI. Dans ce guide, vous apprendrez à créer votre propre extension, à la publier et à la rendre découvrable.

Pour la documentation destinée aux utilisateurs sur l’installation et la gestion des extensions, consultez la référence CLI de hf extensions.

Aperçu

Il existe deux types d’extensions :

1. Extensions de script shell : un fichier exécutable unique (script bash, binaire compilé, etc.) placé à la racine du dépôt.
2. Extensions Python : un paquetage Python standard avec un pyproject.toml. Installé dans un environnement virtuel isolé afin que les dépendances n’entrent pas en conflit avec le système de l’utilisateur.

Les deux types partagent les mêmes conventions :

• Le dépôt GitHub doit être nommé hf-<name> (par exemple, hf-claude, hf-mem).
• Une fois installé, les utilisateurs lancent l’extension avec hf <name> (par exemple, hf claude).
• L'extension est répertoriée dans hf --help sous « Commandes d'extension ».

Lorsqu’un utilisateur exécute hf extensions install [OWNER/]hf-<name>, le système recherche d’abord un fichier binaire/script nommé hf-<name> à la racine du dépôt. S’il est trouvé, il est installé en tant qu’extension de script shell. Sinon, le système installe le dépôt en tant que package Python.

Créer une extension de script shell

L'extension de script shell est le type le plus simple. Il suffit d'un dépôt GitHub contenant un fichier exécutable nommé hf-<name> à la racine.

Les extensions de script shell ne sont pas prises en charge sur Windows. Si votre extension doit fonctionner sur Windows, faites-en plutôt une extension Python.

Exemple minimal

Créez un dépôt nommé hf-hello sur GitHub avec un seul fichier :

hf-hello (à la racine du dépôt) :

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

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

C’est tout ! Les utilisateurs peuvent maintenant l’installer et l’exécuter :

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

Conseils pour les extensions de scripts shell

• Commencez toujours par un shebang (#!/usr/bin/env bash) et set -euo pipefail pour la sécurité.
• Le script reçoit tous les arguments supplémentaires transmis par l'utilisateur. Par exemple, hf hello --name world transmet --name world au script.
• Vous pouvez accéder au jeton Hugging Face de l’utilisateur via la variable d’environnement HF_TOKEN s’il est connecté.
• Ajoutez un manifest.json à la racine du dépôt pour fournir une description (voir Ajouter une description).
• Les dépendances externes (par exemple, fzf, jq, etc.) ne sont pas installées automatiquement avec votre extension. Vérifiez la présence des outils requis au début de votre script et échouez proprement avec un message d’erreur utile s’ils manquent.

Pour un exemple concret, consultez hanouticelina/hf-claude — une extension de script shell qui lance Claude Code avec HF Inference Providers.

Créer une extension Python

Les extensions Python sont des paquets Python complets installés dans un environnement virtuel isolé. C'est le meilleur choix lorsque votre extension a des dépendances Python ou une logique plus complexe.

Exemple minimal

Créez un dépôt nommé hf-hello sur GitHub avec cette structure :

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 partie cruciale est le point d'entrée [project.scripts] : il doit être nommé hf-<name> (ici, hf-hello). C'est ainsi que le CLI hf détecte et exécute votre extension.

Les utilisateurs l'installent et l'exécutent de la même manière :

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

Comment les extensions Python sont installées

Lorsqu’un utilisateur installe une extension Python, les événements suivants se produisent :

1. Un environnement virtuel est créé dans ~/.local/share/hf/extensions/hf-<name>/venv/.
2. Votre package est installé via pip install à partir de l'archive du dépôt GitHub.
3. Le système vérifie qu'un script de console hf-<name> a été créé dans le venv.

Cela signifie que les dépendances de votre extension sont entièrement isolées — elles ne créeront aucun conflit avec les autres packages Python de l’utilisateur.

Pour un exemple concret, consultez alvarobartt/hf-mem — une extension Python qui estime les besoins en mémoire d’inférence pour les modèles HF.

Ajouter une description

La description aide les utilisateurs à comprendre ce que fait votre extension. Elle apparaît dans hf extensions list et dans hf --help.

Le système recherche une description dans l'ordre suivant :

1. manifest.json à la racine du dépôt :

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

2. pyproject.toml champ description (pour les extensions Python) :

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

3. Description du dépôt GitHub (le champ « À propos » de la page du dépôt).

Pour les extensions Python, définir description dans pyproject.toml est l’approche la plus naturelle. Pour les extensions de script shell, utilisez un fichier manifest.json ou définissez la description du dépôt GitHub.

Rendre votre extension découvrable

Pour aider les utilisateurs à trouver votre extension, ajoutez le sujet hf-extension à votre dépôt GitHub :

1. Accédez à votre dépôt sur GitHub.
2. Cliquez sur l’icône d’engrenage située à côté de « À propos » dans la barre latérale droite.
3. Sous « Topics », ajoutez hf-extension.

Il s’agit d’une convention communautaire qui facilite la consultation de toutes les extensions disponibles sur la page du sujet hf-extension.

Les utilisateurs peuvent ensuite découvrir votre extension directement depuis le CLI avec hf extensions search, qui répertorie tous les dépôts GitHub étiquetés avec le sujet hf-extension, triés par nombre d’étoiles :

>>> 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 colonne INSTALLED indique les extensions déjà installées localement. À partir de là, les utilisateurs peuvent installer n'importe quelle extension listée avec hf extensions install <repo>.

Testez votre extension

Lors du développement, vous pouvez installer votre extension directement depuis votre dépôt 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>

Utilisez --force pour écraser une version précédemment installée lors des tests de mises à jour.

Mettre à jour les extensions installées

Une fois une extension installée, vous pouvez la mettre à jour vers la dernière version publiée sur 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 ne met à jour que les extensions déjà installées. Si l’extension n’est pas installée, une erreur est levée. Les extensions déjà à jour sont ignorées.

La version d’une extension est le commit depuis lequel elle a été installée, affiché sous forme de SHA court dans la colonne VERSION de hf extensions list. La colonne LATEST est vérifiée lorsqu’aucun commit plus récent n’est disponible sur GitHub, et l’exécution d’une extension obsolète affiche un indice suggérant hf extensions update <name>. Pour rester dans les limites de débit de GitHub pour les requêtes non authentifiées, hf recherche le dernier commit de chaque extension au plus une fois par jour. Définissez HF_HUB_DISABLE_UPDATE_CHECK=1 pour désactiver ces vérifications.

Si une extension Python cesse de fonctionner parce que l’interpréteur Python avec lequel elle a été installée a été supprimé (par exemple après une mise à niveau de Homebrew), hf extensions update <name> recrée son environnement virtuel.

Règles de nommage

Les noms d'extensions doivent respecter ces règles :

• Le dépôt GitHub doit être nommé hf-<name>.
• <name> doit commencer par une lettre ou un chiffre.
• <name> peut contenir des lettres, des chiffres, ., _ et -.
• <name> ne peut pas entrer en conflit avec une commande intégrée de hf (par exemple, download, upload, auth).

Lors de l’installation, les utilisateurs peuvent soit spécifier le nom complet OWNER/hf-<name>, soit simplement hf-<name> (ce qui correspond par défaut à l’organisation huggingface).

Extensions existantes

Voici quelques extensions de la communauté que vous pouvez utiliser comme référence :