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>이라는 이름의 바이너리/스크립트 파일을 찾습니다. 해당 파일이 있으면 셸 스크립트 확장 프로그램으로 설치합니다. 그렇지 않으면 저장소를 Python 패키지로 설치하도록 폴백합니다.

셸 스크립트 확장 만들기

Shell script 확장자는 가장 간단한 유형입니다. 루트에 hf-<name>이라는 이름의 실행 파일이 있는 GitHub 저장소만 있으면 됩니다.

Windows에서는 Shell 스크립트 확장 기능이 지원되지 않습니다. 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:

셸 스크립트 확장 팁

• 항상 shebang(#!/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 extensions는 격리된 가상 환경에 설치되는 완전한 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을 설정하는 것이 가장 자연스러운 방법입니다. Shell 스크립트 확장 프로그램의 경우, manifest.json 파일을 사용하거나 GitHub 저장소 설명을 설정하세요.

확장 기능을 검색 가능하게 만들기

사용자가 확장 기능을 쉽게 찾을 수 있도록 GitHub 저장소에 hf-extension 주제를 추가하세요:

1. GitHub에서 저장소로 이동하세요.
2. 오른쪽 사이드바의 “About” 옆에 있는 기어 아이콘을 클릭합니다.
3. “Topics”에 hf-extension을 추가합니다.

이것은 hf-extension 토픽 페이지에서 사용 가능한 모든 확장 기능을 쉽게 탐색할 수 있도록 하는 커뮤니티 관례입니다.

사용자는 hf extensions search를 통해 CLI에서 직접 확장 기능을 발견할 수 있습니다. 이 명령은 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는 각 확장 기능의 최신 커밋을 하루에 최대 한 번만 조회합니다. 이러한 확인을 비활성화하려면 HF_HUB_DISABLE_UPDATE_CHECK=1을 설정하세요.

설치에 사용된 Python이 제거되어(예: Homebrew 업그레이드 후) Python 확장 기능이 작동하지 않게 되면, hf extensions update <name>을 실행하면 해당 가상 환경이 다시 생성됩니다.

네이밍 규칙

확장 프로그램 이름은 다음 규칙을 따라야 합니다:

• GitHub 저장소 이름은 hf-<name>이어야 합니다.
• <name>은(는) 문자 또는 숫자로 시작해야 합니다.
• <name>에는 문자, 숫자, ., _, -를 사용할 수 있습니다.
• <name>은 hf의 내장 명령(예: download, upload, auth)과 충돌할 수 없습니다.

설치 시 사용자는 전체 OWNER/hf-<name> 또는 hf-<name>만 지정할 수 있습니다(기본값은 huggingface 조직입니다).

기존 확장

다음은 참고로 사용할 수 있는 커뮤니티 확장 기능입니다: