CLI拡張機能を作成する

hf CLIは拡張機能をサポートしています。拡張機能はコミュニティによって提供されるカスタムコマンドであり、CLIにシームレスに統合されます。拡張機能はパブリックなGitHubリポジトリとしてホストされており、1つのコマンドでインストールできます。インストール後、組み込みのコマンドと同様に、トップレベルのhfコマンドとして表示されます。

このシステムはGitHub CLI 拡張機能に着想を得ています。 このガイドでは、独自の拡張機能を作成し、公開し、検索可能にする方法を学びます。

拡張機能のインストールと管理に関するユーザー向けドキュメントについては、hf extensionsのCLIリファレンスを参照してください。

概要

拡張機能には2つの種類があります:

1. シェルスクリプト拡張: リポジトリのルートに配置される単一の実行可能ファイル（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>という名前のバイナリ/スクリプトファイルを探します。見つかった場合は、シェルスクリプト拡張機能としてインストールします。見つからない場合は、リポジトリをPythonパッケージとしてインストールする処理にフォールバックします。

シェルスクリプトの拡張機能を作成する

シェルスクリプト拡張は最もシンプルなタイプです。ルートにhf-<name>という名前の実行可能ファイルを含むGitHubリポジトリがあれば十分です。

Windows ではシェルスクリプトの拡張機能はサポートされていません。拡張機能が Windows で動作する必要がある場合は、代わりにPython 拡張機能として作成してください。

最小限の例

GitHubにhf-helloという名前のリポジトリを作成し、1つのファイルを含めます:

リポジトリのルートにある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:

シェルスクリプト拡張のヒント

• シェバン（#!/usr/bin/env bash）で開始し、安全性のためにset -euo pipefailを使用してください。
• スクリプトは、ユーザーが渡したすべての追加引数を受け取ります。例えば、hf hello --name world は --name world をスクリプトに渡します。
• ユーザーがログインしている場合、HF_TOKEN環境変数を通じてHugging Faceトークンにアクセスできます。
• リポジトリのルートにmanifest.jsonを追加して、説明を提供します（説明の追加を参照）。
• 外部依存関係（fzf、jq など）は、拡張機能のインストール時に自動的にインストールされません。スクリプトの冒頭で必要なツールを確認し、不足している場合は、役立つエラーメッセージを出力して適切に処理を中断してください。

実際の使用例として、hanouticelina/hf-claude をご覧ください。これは、HF Inference Providers を使用して Claude Code を起動するシェルスクリプトの拡張機能です。

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. パッケージは、GitHubリポジトリのアーカイブからpip installによってインストールされます。
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リポジトリの説明（リポジトリページの「About」欄）。

Python拡張機能の場合、pyproject.tomlでdescriptionを設定するのが最も自然な方法です。 シェルスクリプト拡張機能の場合、manifest.jsonファイルを使用するか、GitHubリポジトリの説明を設定してください。

拡張機能を発見可能にする

ユーザーがあなたの拡張機能を発見しやすくするために、GitHub リポジトリにhf-extensionトピックを追加してください:

1. GitHubのレポジトリに移動します。
2. 右側のサイドバーにある「About」の横にある歯車アイコンをクリックします。
3. 「Topics」にhf-extensionを追加します。

これはコミュニティの慣例であり、hf-extension トピックページで利用可能なすべての拡張機能を簡単に閲覧できるようにします。

その後、ユーザーはhf extensions searchコマンドで拡張機能を直接検索できます。このコマンドは、hf-extensionトピックでタグ付けされたすべてのGitHubリポジトリを、スター数順にリスト表示します。

>>> 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は、インストール済みの拡張機能のみを更新します。拡張機能がインストールされていない場合、エラーが発生します。すでに最新バージョンの拡張機能はスキップされます。

拡張機能のバージョンは、インストール元のコミットであり、hf extensions listのVERSION列に短いSHAとして表示されます。LATEST列は、GitHub上で新しいコミットが利用可能かどうかを確認するために使用され、古い拡張機能を実行すると、hf extensions update <name>の実行を促すヒントが表示されます。GitHubの非認証リクエストのレート制限内に収めるため、hfは各拡張機能の最新コミットを1日最大1回のみ参照します。これらのチェックを無効にするには、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組織がデフォルトとして使用されます）。

既存の拡張機能

以下は、参考として使用できるコミュニティ拡張機能の例です：