Criar uma extensão de CLI

O CLI hf suporta extensões, comandos personalizados fornecidos pela comunidade que se integram perfeitamente ao CLI. As extensões são hospedadas como repositórios públicos no GitHub e podem ser instaladas com um único comando. Uma vez instaladas, elas aparecem como comandos de nível superior do hf, assim como os embutidos.

Este sistema é inspirado nas extensões do GitHub CLI. Neste guia, você aprenderá a criar sua própria extensão, publicá-la e torná-la descobrível.

Para documentação voltada ao usuário sobre a instalação e o gerenciamento de extensões, consulte a referência da CLI para hf extensions.

Visão geral

Existem dois tipos de extensões:

1. Extensões de script de shell: um único arquivo executável (script bash, binário compilado, etc.) colocado na raiz do repositório.
2. Extensões em Python: um pacote Python padrão com um pyproject.toml. Instalado em um ambiente virtual isolado para que as dependências não conflitem com o sistema do usuário.

Ambos os tipos compartilham as mesmas convenções:

• O repositório do GitHub deve ser nomeado hf-<name> (por exemplo, hf-claude, hf-mem).
• Uma vez instalado, os usuários executam a extensão com hf <name> (por exemplo, hf claude).
• A extensão está listada em hf --help sob “Extension commands”.

Quando um usuário executa hf extensions install [OWNER/]hf-<name>, o sistema primeiro procura um arquivo de binário/script chamado hf-<name> na raiz do repositório. Se encontrado, ele instala como uma extensão de script de shell. Caso contrário, ele recorre à instalação do repositório como um pacote Python.

Crie uma extensão de script de shell

A extensão de script de shell é o tipo mais simples. Você só precisa de um repositório do GitHub com um arquivo executável chamado hf-<name> na raiz.

Extensões de script de shell não são suportadas no Windows. Se sua extensão deve funcionar no Windows, crie uma extensão em Python em vez disso.

Exemplo mínimo

Crie um repositório chamado hf-hello no GitHub com um único arquivo:

hf-hello (na raiz do repositório):

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

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

É isso! Agora os usuários podem instalar e executá-lo:

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

Dicas para extensões de scripts de shell

• Comece sempre com um shebang (#!/usr/bin/env bash) e set -euo pipefail para segurança.
• O script recebe todos os argumentos extras passados pelo usuário. Por exemplo, hf hello --name world passa --name world para o script.
• Você pode acessar o token do Hugging Face do usuário por meio da variável de ambiente HF_TOKEN se ele estiver conectado.
• Adicione um manifest.json na raiz do repositório para fornecer uma descrição (veja Adicionar uma descrição).
• As dependências externas (por exemplo, fzf, jq, etc.) não são instaladas automaticamente com sua extensão. Verifique as ferramentas necessárias no início do seu script e falhe de forma graciosa com uma mensagem de erro útil caso estejam ausentes.

Para um exemplo do mundo real, veja hanouticelina/hf-claude — uma extensão de script de shell que inicia o Claude Code com os HF Inference Providers.

Crie uma extensão em Python

Extensões em Python são pacotes Python completos instalados em um ambiente virtual isolado. Esta é a melhor escolha quando sua extensão possui dependências em Python ou lógica mais complexa.

Exemplo mínimo

Crie um repositório chamado hf-hello no GitHub com esta estrutura:

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

A parte crítica é o ponto de entrada [project.scripts]: ele deve ser nomeado hf-<name> (aqui, hf-hello). É assim que a CLI hf descobre e executa sua extensão.

Os usuários instalam e executam da mesma forma:

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

Como as extensões do Python são instaladas

Quando um usuário instala uma extensão do Python, o seguinte acontece:

1. Um ambiente virtual é criado em ~/.local/share/hf/extensions/hf-<name>/venv/.
2. Seu pacote é instalado via pip install a partir do arquivo do repositório do GitHub.
3. O sistema verifica se um script de console hf-<name> foi criado no venv.

Isso significa que as dependências da sua extensão estão totalmente isoladas — elas não conflitarão com os outros pacotes Python do usuário.

Para um exemplo do mundo real, veja alvarobartt/hf-mem — uma extensão em Python que estima os requisitos de memória de inferência para modelos do HF.

Adicione uma descrição

A descrição ajuda os usuários a entender o que sua extensão faz. Ela aparece em hf extensions list e em hf --help.

O sistema procura uma descrição na seguinte ordem:

1. manifest.json na raiz do repositório:

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

2. pyproject.toml campo description (para extensões em Python):

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

3. Descrição do repositório no GitHub (o campo “About” na página do repositório).

Para extensões em Python, definir description em pyproject.toml é a abordagem mais natural. Para extensões de script de shell, use um arquivo manifest.json ou defina a descrição do repositório no GitHub.

Torne sua extensão descobrível

Para ajudar os usuários a encontrar sua extensão, adicione o tópico hf-extension ao seu repositório no GitHub:

1. Acesse seu repositório no GitHub.
2. Clique no ícone de engrenagem ao lado de “About” na barra lateral à direita.
3. Em “Tópicos”, adicione hf-extension.

Esta é uma convenção da comunidade que facilita a navegação por todas as extensões disponíveis na página do tópico hf-extension.

Em seguida, os usuários podem descobrir sua extensão diretamente pela CLI com hf extensions search, que lista todos os repositórios do GitHub marcados com o tópico hf-extension, ordenados por estrelas:

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

A coluna INSTALLED mostra quais extensões já estão instaladas localmente. A partir daí, os usuários podem instalar qualquer extensão listada com hf extensions install <repo>.

Teste sua extensão

Durante o desenvolvimento, você pode instalar sua extensão diretamente do seu repositório no 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 sobrescrever uma versão instalada anteriormente ao testar atualizações.

Atualizar extensões instaladas

Depois que uma extensão é instalada, você pode atualizá-la para a versão mais recente publicada no 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 atualiza apenas as extensões que já estão instaladas. Se a extensão não estiver instalada, um erro é lançado. As extensões que já estão atualizadas são ignoradas.

A versão de uma extensão é o commit do qual ela foi instalada, exibido como um SHA curto na coluna VERSION de hf extensions list. A coluna LATEST é verificada quando nenhum commit mais novo está disponível no GitHub, e a execução de uma extensão desatualizada exibe uma dica sugerindo hf extensions update <name>. Para permanecer dentro dos limites de taxa do GitHub para solicitações não autenticadas, o hf consulta o commit mais recente de cada extensão no máximo uma vez por dia. Defina HF_HUB_DISABLE_UPDATE_CHECK=1 para desativar essas verificações.

Se uma extensão Python parar de funcionar porque o Python com o qual foi instalada foi removido (por exemplo, após uma atualização do Homebrew), hf extensions update <name> recria seu ambiente virtual.

Regras de nomenclatura

Os nomes de extensões devem seguir estas regras:

• O repositório do GitHub deve ser nomeado hf-<name>.
• <name> deve começar com uma letra ou um dígito.
• <name> pode conter letras, dígitos, ., _ e -.
• <name> não pode conflitar com um comando embutido do hf (por exemplo, download, upload, auth).

Ao instalar, os usuários podem especificar o OWNER/hf-<name> completo ou apenas hf-<name> (que padrão para a organização huggingface).

Extensões existentes

Aqui estão algumas extensões da comunidade que você pode usar como referência: