创建 CLI 扩展

hf CLI 支持扩展，即由社区提供的自定义命令，可无缝集成到 CLI 中。扩展以公共 GitHub 仓库的形式托管，可通过一条命令安装。安装后，它们会像内置命令一样，作为顶层 hf 命令出现。

该系统受 GitHub CLI 扩展 的启发。 在本指南中，你将学习如何创建自己的扩展、发布它并使其可被发现。

有关安装和管理扩展的用户文档，请参阅 hf extensions 的 CLI 参考。

概述

有两种类型的扩展：

1. Shell 脚本扩展：放置在仓库根目录下的单个可执行文件（bash 脚本、编译后的二进制文件等）。
2. Python 扩展：一个包含 pyproject.toml 的标准 Python 包。它安装在隔离的虚拟环境中，以避免依赖项与用户系统发生冲突。

这两种类型遵循相同的约定：

• 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 扩展。

最小示例

在 GitHub 上创建一个名为 hf-hello 的仓库，其中包含一个文件：

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:

Shell 脚本扩展技巧

• 始终从 shebang（#!/usr/bin/env bash）开始，并添加 set -euo pipefail 以确保安全性。
• 该脚本会接收用户传入的所有额外参数。例如，hf hello --name world 会将 --name world 传递给脚本。
• 如果用户已登录，您可以通过 HF_TOKEN 环境变量访问其 Hugging Face 令牌。
• 在仓库根目录添加一个 manifest.json 以提供描述（参见 添加描述）。
• External dependencies (e.g., fzf, jq, etc.) are not installed automatically with your extension. Check for required tools at the start of your script and fail gracefully with a helpful error message if they are missing.

一个实际示例，请参阅 hanouticelina/hf-claude —— 一个用于通过 HF Inference Providers 启动 Claude Code 的 shell 脚本扩展。

创建 Python 扩展

Python 扩展是安装在隔离虚拟环境中的完整 Python 包。当您的扩展包含 Python 依赖项或更复杂的逻辑时，这是最佳选择。

最小示例

在 GitHub 上创建一个名为 hf-hello 的仓库，其结构如下：

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）。 hf CLI 正是通过这种方式发现并执行你的扩展的。

用户以相同的方式安装并运行它：

>>> 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 —— 一个用于估算 HF 模型推理内存需求的 Python 扩展。

添加描述

描述有助于用户了解您的扩展功能。它会显示在 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 仓库描述（仓库页面上的“关于”字段）。

对于 Python 扩展，在 pyproject.toml 中设置 description 是最自然的方式。 对于 shell 脚本扩展，请使用 manifest.json 文件或设置 GitHub 仓库描述。

让您的扩展可被发现

为了帮助用户找到您的扩展，请在您的 GitHub 仓库中添加 hf-extension 主题：

1. 前往您在 GitHub 上的仓库。
2. 点击右侧边栏中“关于”旁边的齿轮图标。
3. 在“Topics”下，添加 hf-extension。

这是一种社区约定，方便大家在 hf-extension 主题页面 上浏览所有可用的扩展。

之后，用户可以直接通过 CLI 使用 hf extensions search 来发现您的扩展，该命令会列出所有带有 hf-extension 主题的 GitHub 仓库，并按 star 数排序：

>>> 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 的形式显示在 hf extensions list 的 VERSION 列中。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 组织）。

现有扩展

以下是一些可供参考的社区扩展：