hf

Hugging Face Hub CLI

用法：

$ hf [OPTIONS] [COMMAND] [ARGS]...

选项：

• --skills：将 hf-cli 的 SKILL.md 打印到标准输出（hf skills preview 的别名）。
• --install-completion：为当前 shell 安装自动补全功能。
• --show-completion：显示当前 shell 的补全配置，以便复制或自定义安装。
• --help：显示此消息并退出。

命令：

• auth：管理身份验证（登录、登出等）。
• buckets：用于与存储桶交互的命令。
• cache：管理本地缓存目录。
• collections：与 Hub 上的集合进行交互。
• cp：在本地路径、仓库和存储桶之间复制文件。
• datasets：与 Hub 上的数据集进行交互。
• discussions：在 Hub 上管理讨论和拉取请求。
• download：从 Hub 下载文件。
• endpoints：管理 Hugging Face Inference Endpoints。
• env：打印有关环境的信息。
• extensions：管理 hf CLI 扩展。[别名：ext]
• jobs：在 Hub 上运行和管理 Jobs。
• lfs-enable-largefiles：配置您的仓库以启用上传大于 5GB 的文件。
• lfs-multipart-upload：用于分块上传的 git-lfs 内部自定义传输代理。
• models：与 Hub 上的模型进行交互。
• papers：与 Hub 上的论文进行交互。
• repos：管理 Hub 上的仓库。
• sandbox：在 Hugging Face Jobs 上运行和管理实验沙箱。
• skills：管理 AI 助手的技能。
• spaces：与 Hub 上的 spaces 进行交互。
• sync：在本地目录和存储桶之间同步文件。
• update：将 hf CLI 更新到最新版本。
• upload：将文件或文件夹上传到 Hub。
• version：打印 hf 版本信息。
• webhooks：在 Hub 上管理 Webhooks。

hf auth

管理身份验证（登录、登出等）。

用法：

$ hf auth [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• list：列出所有已存储的访问令牌。[别名：ls]
• login：从浏览器登录，或使用 huggingface.co/settings/tokens 中的令牌登录。
• logout：从特定令牌注销。
• switch：在访问令牌之间切换。
• token：将当前访问令牌打印到标准输出。
• whoami：查看当前登录的 huggingface.co 账户。

hf auth list

列出所有已存储的访问令牌。[别名: ls]

用法：

$ hf auth list [OPTIONS]

选项：

• --help：显示此消息并退出。

示例 $ hf auth list

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf auth login

从您的浏览器登录，或使用来自 huggingface.co/settings/tokens 的令牌。

用法：

$ hf auth login [OPTIONS]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --add-to-git-credential / --no-add-to-git-credential：保存到 git credential helper。仅当您计划直接运行 git 命令时才有用。 [默认值：no-add-to-git-credential]
• --force / --no-force：即使已登录，也强制重新登录。 [默认值：no-force]
• --help：显示此消息并退出。

示例 $ hf auth login $ hf auth login —token $HF_TOKEN $ hf auth login —token $HF_TOKEN —add-to-git-credential $ hf auth login —force

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf auth logout

从特定令牌注销。

用法：

$ hf auth logout [OPTIONS]

选项：

• --token-name TEXT：要注销的令牌名称
• --help：显示此消息并退出。

示例 $ hf auth logout $ hf auth logout —token-name my-token

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf auth switch

在访问令牌之间切换。

用法：

$ hf auth switch [OPTIONS]

选项：

• --token-name TEXT：要切换到的令牌名称
• --add-to-git-credential / --no-add-to-git-credential：保存到 git credential helper。仅当您计划直接运行 git 命令时才有用。 [默认值：no-add-to-git-credential]
• --help：显示此消息并退出。

示例 $ hf auth switch $ hf auth switch —token-name my-token

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf auth token

将当前访问令牌打印到标准输出。

用法：

$ hf auth token [OPTIONS]

选项：

• --help：显示此消息并退出。

示例 $ hf auth token $ hf auth token | xargs curl -H ‘Authorization: Bearer {}’

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf auth whoami

查看当前登录的 huggingface.co 账户。

用法：

$ hf auth whoami [OPTIONS]

选项：

• --help：显示此消息并退出。

示例 $ hf auth whoami $ hf auth whoami —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets

用于与存储桶交互的命令。

用法：

$ hf buckets [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• cp：在本地路径、仓库和存储桶之间复制文件。
• create：创建一个新的存储桶。
• delete：删除存储桶。
• info：获取存储桶的信息。
• list：列出存储桶或存储桶中的文件。[别名：ls]
• move：将存储桶移动（重命名）到新的名称或命名空间。
• remove：从存储桶中删除文件。[别名：rm]
• settings：更新存储桶设置（可见性）。
• sync：在本地目录和存储桶之间同步文件。

hf buckets cp

在本地路径、仓库和存储桶之间复制文件。

处理上传（本地/stdin -> 仓库/存储桶）、下载（仓库/存储桶 -> 本地/stdout）以及远程到远程的复制（仓库/存储桶 -> 仓库/存储桶）。不支持存储桶到仓库以及本地到本地的复制。对于目录，请使用 hf upload/hf download（仓库）或 hf buckets sync（存储桶）。远程到远程的复制仅在相同的存储区域内有效（https://huggingface.co/docs/hub/storage-regions）。

用法：

$ hf buckets cp [OPTIONS] SRC [DST]

参数：

• SRC：源：本地文件、hf:// URI（仓库或存储桶），或 - 表示标准输入。 [必填]
• [DST]：目标：本地路径、hf:// URI（仓库或存储桶），或 - 表示标准输出。

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets cp hf://buckets/username/my-bucket/config.json config.json $ hf buckets cp hf://buckets/username/my-bucket/data.csv data/ $ hf buckets cp hf://buckets/username/my-bucket/config.json - $ hf buckets cp model.safetensors hf://buckets/username/my-bucket/model.safetensors $ hf buckets cp config.json hf://buckets/username/my-bucket/logs/ $ hf buckets cp - hf://buckets/username/my-bucket/config.json $ hf buckets cp hf://buckets/username/my-bucket/data.csv hf://buckets/username/dest-bucket/ $ hf buckets cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/dest-bucket/logs/

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets create

创建一个新的存储桶。

用法：

$ hf buckets create [OPTIONS] BUCKET_ID

参数：

• BUCKET_ID：存储桶 ID：bucket_name、namespace/bucket_name 或 hf://buckets/namespace/bucket_name [必填]

选项：

• --private：创建一个私有存储桶。
• --region [us|eu]：创建存储桶所在的云区域。可以是 ‘us’ 或 ‘eu’ 之一。需要 Team 套餐或更高版本。
• --exist-ok：如果存储桶已存在，则不引发错误。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets create my-bucket $ hf buckets create user/my-bucket $ hf buckets create hf://buckets/user/my-bucket $ hf buckets create user/my-bucket —private $ hf buckets create user/my-bucket —exist-ok $ hf buckets create user/my-bucket —region us

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets delete

删除一个存储桶。

这将删除整个存储桶及其所有内容。请使用 hf buckets rm 来删除单个文件。

用法：

$ hf buckets delete [OPTIONS] BUCKET_ID

参数：

• BUCKET_ID：存储桶 ID：namespace/bucket_name 或 hf://buckets/namespace/bucket_name [必填]

选项：

• -y, --yes：跳过确认提示。
• --missing-ok：如果存储桶不存在，则不引发错误。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets delete user/my-bucket $ hf buckets delete hf://buckets/user/my-bucket $ hf buckets delete user/my-bucket —yes $ hf buckets delete user/my-bucket —missing-ok

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets info

获取存储桶的信息。

用法：

$ hf buckets info [OPTIONS] BUCKET_ID

参数：

• BUCKET_ID：存储桶 ID：namespace/bucket_name 或 hf://buckets/namespace/bucket_name [必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets info user/my-bucket $ hf buckets info hf://buckets/user/my-bucket

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets list

列出存储桶或存储桶中的文件。[别名: ls]

在不带参数或传入命名空间时调用，列出存储桶。 在传入存储桶 ID（namespace/bucket_name）时调用，列出存储桶中的文件。

用法：

$ hf buckets list [OPTIONS] [ARGUMENT]

参数：

• [ARGUMENT]：用于列出存储桶的命名空间（用户或组织），或用于列出文件的存储桶 ID（namespace/bucket_name(/prefix) 或 hf://buckets/…）。

选项：

• -h, --human-readable：以人类可读的格式显示大小。
• --tree：以树状格式列出文件（仅用于列出文件）。
• -R, --recursive：递归列出文件（仅用于列出文件）。
• --search TEXT：搜索查询。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets list $ hf buckets list huggingface $ hf buckets list —search “my-prefix” $ hf buckets list user/my-bucket $ hf buckets list user/my-bucket -R $ hf buckets list user/my-bucket -h $ hf buckets list user/my-bucket —tree $ hf buckets list user/my-bucket —tree -h $ hf buckets list hf://buckets/user/my-bucket $ hf buckets list user/my-bucket/sub -R

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets move

将存储桶移动（重命名）到新的名称或命名空间。

用法：

$ hf buckets move [OPTIONS] FROM_ID TO_ID

参数：

• FROM_ID：源存储桶 ID：namespace/bucket_name 或 hf://buckets/namespace/bucket_name [必填]
• TO_ID：目标存储桶 ID：namespace/bucket_name 或 hf://buckets/namespace/bucket_name [必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets move user/old-bucket user/new-bucket $ hf buckets move user/my-bucket my-org/my-bucket $ hf buckets move hf://buckets/user/old-bucket hf://buckets/user/new-bucket

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets remove

从存储桶中删除文件。[别名: rm]

若要删除整个存储桶，请改用 hf buckets delete。

用法：

$ hf buckets remove [OPTIONS] ARGUMENT

参数：

• ARGUMENT：存储桶路径：namespace/bucket_name/path 或 hf://buckets/namespace/bucket_name/path。使用 —recursive 时，也接受 namespace/bucket_name 以指定所有文件。 [必填]

选项：

• -R, --recursive：递归删除给定前缀下的文件。
• -y, --yes：跳过确认提示。
• --dry-run：预览将被删除的内容，而不实际执行删除操作。
• --include TEXT：仅包含匹配该模式的文件（可指定多个）。需要 —recursive。
• --exclude TEXT：排除匹配该模式的文件（可指定多个）。需要 —recursive。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets remove user/my-bucket/file.txt $ hf buckets rm hf://buckets/user/my-bucket/file.txt $ hf buckets rm user/my-bucket/logs/ —recursive $ hf buckets rm user/my-bucket —recursive —include “*.tmp” $ hf buckets rm user/my-bucket/data/ —recursive —dry-run

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets 设置

更新存储桶设置（可见性）。

用法：

$ hf buckets settings [OPTIONS] BUCKET_ID

参数：

• BUCKET_ID：存储桶 ID：namespace/bucket_name 或 hf://buckets/namespace/bucket_name [必填]

选项：

• --private：将存储桶设为私有。
• --public：将存储桶设为公开。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets settings user/my-bucket —private $ hf buckets settings user/my-bucket —public $ hf buckets settings hf://buckets/user/my-bucket —private

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf buckets sync

在本地目录和存储桶之间同步文件。

用法：

$ hf buckets sync [OPTIONS] [SOURCE] [DEST]

参数：

• [SOURCE]：源路径：本地目录或 hf://buckets/namespace/bucket_name(/prefix)
• [DEST]：目标路径：本地目录或 hf://buckets/namespace/bucket_name(/prefix)

选项：

• --delete / --no-delete：删除源中不存在的目标文件。 [默认值：no-delete]
• --ignore-times：仅根据文件大小跳过文件，忽略修改时间。
• --ignore-sizes：仅根据修改时间跳过文件，忽略文件大小。
• --plan TEXT：将同步计划保存为 JSONL 文件以供审查，而不是执行。
• --apply TEXT：应用之前保存的计划文件。
• --dry-run：以 JSONL 格式将同步计划打印到标准输出，而不执行。
• --include TEXT：包含匹配该模式的文件（可指定多个）。
• --exclude TEXT：排除匹配该模式的文件（可指定多个）。
• --filter-from TEXT：从文件中读取包含/排除模式。
• --existing：在接收端跳过创建新文件（仅更新现有文件）。
• --ignore-existing：跳过接收端已存在的文件（仅创建新文件）。
• -v, --verbose：显示带有推理过程的详细日志。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf buckets sync ./data hf://buckets/user/my-bucket $ hf buckets sync hf://buckets/user/my-bucket ./data $ hf buckets sync ./data hf://buckets/user/my-bucket —delete $ hf buckets sync hf://buckets/user/my-bucket ./data —include ”.safetensors” —exclude ”.tmp” $ hf buckets sync ./data hf://buckets/user/my-bucket —plan sync-plan.jsonl $ hf buckets sync —apply sync-plan.jsonl $ hf buckets sync ./data hf://buckets/user/my-bucket —dry-run $ hf buckets sync ./data hf://buckets/user/my-bucket —dry-run | jq .

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf cache

管理本地缓存目录。

用法：

$ hf cache [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• list：列出已缓存的仓库或修订版本。[别名：ls]
• prune：从缓存中移除已分离的版本和不完整的下载。
• rm：删除缓存的仓库、修订版本或文件。
• verify：从缓存或本地目录中验证单个仓库修订版的校验和。

hf cache list

列出已缓存的仓库或修订版本。[别名: ls]

用法：

$ hf cache list [OPTIONS]

选项：

• --cache-dir TEXT：要扫描的缓存目录（默认为 Hugging Face 缓存）。
• --revisions / --no-revisions：在输出中包含修订版本，而不是聚合后的仓库。 [默认值：no-revisions]
• -f, --filter TEXT：筛选条目（例如 ‘size>1GB’、‘type=model’、‘accessed>7d’）。可多次使用。
• --sort [accessed|accessed:asc|accessed:desc|modified|modified:asc|modified:desc|name|name:asc|name:desc|size|size:asc|size:desc]：按指定键对条目进行排序。支持的键：‘accessed’、‘modified’、‘name’、‘size’。在键后追加 ‘:asc’ 或 ‘:desc’ 可显式指定排序顺序（例如 ‘modified:asc’）。默认值：‘accessed’、‘modified’ 和 ‘size’ 默认为 ‘desc’（最新/最大优先）；‘name’ 默认为 ‘asc’（按字母顺序）。
• --limit INTEGER：限制返回的结果数量。排序后仅返回前 N 条记录。
• --show-warnings / --no-show-warnings：显示有关缓存不一致的警告。 [默认值：no-show-warnings]
• --help：显示此消息并退出。

示例 $ hf cache ls $ hf cache ls —revisions $ hf cache ls —filter “size>1GB” —limit 20 $ hf cache ls —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf cache prune

从缓存中移除已分离的版本和不完整的下载。

用法：

$ hf cache prune [OPTIONS]

选项：

• --cache-dir TEXT：要扫描的缓存目录（默认为 Hugging Face 缓存）。
• -y, --yes：跳过确认提示。
• --dry-run / --no-dry-run：预览删除操作，但不实际移除任何内容。 [默认值：no-dry-run]
• --help：显示此消息并退出。

示例 $ hf cache prune $ hf cache prune —dry-run

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf cache rm

删除已缓存的仓库、修订版本或文件。

用法：

$ hf cache rm [OPTIONS] TARGETS...

参数：

• TARGETS...：要删除的一个或多个仓库 ID（例如 model/bert-base-uncased）、hf:// URI（仓库或文件）或修订哈希值。[必填]

选项：

• --cache-dir TEXT：要扫描的缓存目录（默认为 Hugging Face 缓存）。
• -y, --yes：跳过确认提示。
• --dry-run / --no-dry-run：预览删除操作，但不实际移除任何内容。 [默认值：no-dry-run]
• --help：显示此消息并退出。

示例 $ hf cache rm model/gpt2 $ hf cache rm hf://models/openai-community/gpt2 $ hf cache rm hf://models/openai-community/gpt2/model.safetensors $ hf cache rm <revision_hash> $ hf cache rm model/gpt2 —dry-run $ hf cache rm model/gpt2 —yes

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf cache verify

从缓存或本地目录中验证单个仓库修订版的校验和。

示例：

• 验证缓存中的主修订版本：hf cache verify gpt2
• 验证特定修订版本：hf cache verify gpt2 --revision refs/pr/1
• 验证数据集：hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset
• 验证本地目录：hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo

用法：

$ hf cache verify [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --cache-dir TEXT：从缓存验证文件时使用的缓存目录（默认为 Hugging Face 缓存）。
• --local-dir TEXT：如果设置，则验证此目录下的文件，而不是缓存中的文件。
• --fail-on-missing-files：如果某些文件在远程存在但在本地缺失，则失败。
• --fail-on-extra-files：如果某些文件在本地存在但在远程修订版本中不存在，则失败。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf cache verify gpt2 $ hf cache verify gpt2 —revision refs/pr/1 $ hf cache verify my-dataset —repo-type dataset

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf 集合

在 Hub 上与集合进行交互。

用法：

$ hf collections [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• add-item：向集合中添加一个项目。
• create：在 Hub 上创建一个新的 collection。
• delete：从 Hub 中删除一个集合。
• delete-item：从集合中删除一个项目。
• info：获取 Hub 上某个 collection 的信息。
• list：列出 Hub 上的集合。[别名：ls]
• update：更新 Hub 上集合的元数据。
• update-item：更新集合中的某个项目。

hf collections add-item

向集合中添加一个项目。

用法：

$ hf collections add-item [OPTIONS] COLLECTION_SLUG ITEM_ID ITEM_TYPE:{model|dataset|space|paper|collection|bucket}

参数：

• COLLECTION_SLUG：集合的 slug（例如 ‘username/collection-slug’）。[必填]
• ITEM_ID：要添加的条目的 ID（对于仓库为 repo_id，对于论文为论文 ID）。[必填]
• ITEM_TYPE:{model|dataset|space|paper|collection|bucket}：项目的类型（model、dataset、space、paper、collection 或 bucket）。[必填]

选项：

• --note TEXT：要附加到该项目的备注（最多 500 个字符）。
• --exists-ok / --no-exists-ok：如果该条目已存在于集合中，则不引发错误。 [默认值：no-exists-ok]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections add-item username/my-collection moonshotai/kimi-k2 model $ hf collections add-item username/my-collection Qwen/DeepPlanning dataset —note “Useful dataset” $ hf collections add-item username/my-collection Tongyi-MAI/Z-Image space

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf collections create

在 Hub 上创建一个新的集合。

用法：

$ hf collections create [OPTIONS] TITLE

参数：

• TITLE：该集合的标题。 [必填]

选项：

• --namespace TEXT：命名空间（用户名或组织）。默认值为已认证用户。
• --description TEXT：集合的描述（最多 150 个字符）。
• --private / --no-private：创建私有集合。 [默认值：no-private]
• --exists-ok / --no-exists-ok：如果集合已存在，则不引发错误。 [默认值：no-exists-ok]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections create “My Models” $ hf collections create “My Models” —description “A collection of my favorite models” —private $ hf collections create “Org Collection” —namespace my-org

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf collections delete

从 Hub 中删除一个集合。

用法：

$ hf collections delete [OPTIONS] COLLECTION_SLUG

参数：

• COLLECTION_SLUG：集合的 slug（例如 ‘username/collection-slug’）。[必填]

选项：

• --missing-ok / --no-missing-ok：如果集合不存在，则不引发错误。 [默认值：no-missing-ok]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections delete username/my-collection $ hf collections delete username/my-collection —missing-ok

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf collections delete-item

从集合中删除一个项目。

用法：

$ hf collections delete-item [OPTIONS] COLLECTION_SLUG ITEM_OBJECT_ID

参数：

• COLLECTION_SLUG：集合的 slug（例如 ‘username/collection-slug’）。[必填]
• ITEM_OBJECT_ID：集合中该项目的 ID（从 ‘hf collections info’ 返回的 item_object_id 字段中获取。[必填]

选项：

• --missing-ok / --no-missing-ok：如果该项不存在，则不引发错误。 [默认值：no-missing-ok]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

hf collections info

获取 Hub 上某个集合的信息。

用法：

$ hf collections info [OPTIONS] COLLECTION_SLUG

参数：

• COLLECTION_SLUG：集合的 slug（例如 ‘username/collection-slug’）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections info username/my-collection-slug

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf collections list

列出 Hub 上的集合。[alias: ls]

用法：

$ hf collections list [OPTIONS]

选项：

• --owner TEXT：按所有者用户名或组织进行筛选。
• --item TEXT：筛选包含特定项目（例如“models/gpt2”、“datasets/squad”、“papers/2311.12983”）的集合。
• --sort [lastModified|trending|upvotes]：按最后修改时间、热门程度或点赞数对结果进行排序。
• --limit INTEGER：限制结果数量。 [默认值：10]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections ls $ hf collections ls —owner nvidia $ hf collections ls —item models/teknium/OpenHermes-2.5-Mistral-7B —limit 10

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf collections update

在 Hub 上更新集合的元数据。

用法：

$ hf collections update [OPTIONS] COLLECTION_SLUG

参数：

• COLLECTION_SLUG：集合的 slug（例如 ‘username/collection-slug’）。[必填]

选项：

• --title TEXT：集合的新标题。
• --description TEXT：集合的新描述（最多 150 个字符）。
• --position INTEGER：该集合在所有者列表中的新位置。
• --private / --no-private：该集合是否应为私有。
• --theme TEXT：集合的主题颜色（例如，‘green’、‘blue’）。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections update username/my-collection —title “New Title” $ hf collections update username/my-collection —description “Updated description” $ hf collections update username/my-collection —private —theme green

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf collections update-item

更新集合中的某个项目。

用法：

$ hf collections update-item [OPTIONS] COLLECTION_SLUG ITEM_OBJECT_ID

参数：

• COLLECTION_SLUG：集合的 slug（例如 ‘username/collection-slug’）。[必填]
• ITEM_OBJECT_ID：集合中该项目的 ID（来自 ‘item_object_id’ 字段，而非 repo_id）。[必填]

选项：

• --note TEXT：该条目的新备注（最多 500 个字符）。
• --position INTEGER：该条目在集合中的新位置。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf collections update-item username/my-collection ITEM_OBJECT_ID —note “Updated note” $ hf collections update-item username/my-collection ITEM_OBJECT_ID —position 0

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf cp

在本地路径、仓库和存储桶之间复制文件。

处理上传（本地/stdin -> 仓库/存储桶）、下载（仓库/存储桶 -> 本地/stdout）以及远程到远程的复制（仓库/存储桶 -> 仓库/存储桶）。不支持存储桶到仓库以及本地到本地的复制。对于目录，请使用 hf upload/hf download（仓库）或 hf buckets sync（存储桶）。远程到远程的复制仅在相同的存储区域内有效（https://huggingface.co/docs/hub/storage-regions）。

用法：

$ hf cp [OPTIONS] SRC [DST]

参数：

• SRC：源：本地文件、hf:// URI（仓库或存储桶），或 - 表示标准输入。 [必填]
• [DST]：目标：本地路径、hf:// URI（仓库或存储桶），或 - 表示标准输出。

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf cp hf://username/my-model/config.json $ hf cp hf://username/my-model/config.json ./config.json $ hf cp hf://datasets/username/my-dataset/data.csv ./data/ $ hf cp hf://buckets/username/my-bucket/config.json - $ hf cp ./model.safetensors hf://username/my-model/model.safetensors $ hf cp ./config.json hf://buckets/username/my-bucket/logs/ $ hf cp - hf://buckets/username/my-bucket/config.json $ hf cp hf://username/source-model/ hf://username/dest-model/ $ hf cp hf://datasets/username/my-dataset/processed/ hf://buckets/username/my-bucket/processed/ $ hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/ # copies contents only

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf datasets

与 Hub 上的数据集进行交互。

用法：

$ hf datasets [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• card：获取 Hub 上数据集的数据集卡片（README）。
• info：获取 Hub 上数据集的信息。
• leaderboard：列出数据集排行榜中的模型分数。
• list：列出 Hub 上的数据集，或数据集仓库中的文件。[别名：ls]
• parquet：列出数据集可用的 parquet 文件 URL。
• sql：使用 DuckDB 针对数据集的 parquet URL 执行原始 SQL 查询。

hf 数据集卡片

获取 Hub 上数据集的数据集卡片（README）。

用法：

$ hf datasets card [OPTIONS] DATASET_ID

参数：

• DATASET_ID：数据集 ID（例如 username/repo-name）。[必填]

选项：

• --metadata：仅输出卡片中的元数据。
• --text：仅输出文本正文（不包含元数据）。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf datasets card HuggingFaceFW/fineweb $ hf datasets card HuggingFaceFW/fineweb —metadata $ hf datasets card HuggingFaceFW/fineweb —metadata —format json $ hf datasets card HuggingFaceFW/fineweb —text

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf datasets info

获取 Hub 上数据集的信息。

用法：

$ hf datasets info [OPTIONS] DATASET_ID

参数：

• DATASET_ID：数据集 ID（例如 username/repo-name）。[必填]

选项：

• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --expand TEXT：要返回的逗号分隔的属性。使用时，仅返回列出的属性（以及 id）。示例：‘—expand=downloads,likes,tags’。有效值：author, cardData, citation, createdAt, description, disabled, downloads, downloadsAllTime, gated, lastModified, likes, mainSize, paperswithcode_id, private, resourceGroup, sha, siblings, tags, trendingScore, usedStorage。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf datasets info HuggingFaceFW/fineweb $ hf datasets info my-dataset —expand downloads,likes,tags

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf datasets 排行榜

列出数据集排行榜中的模型分数。此命令有助于为特定任务查找最佳模型，或根据基准分数比较模型。使用 hf datasets ls —filter benchmark:official 可列出可用的排行榜。

用法：

$ hf datasets leaderboard [OPTIONS] DATASET_ID

参数：

• DATASET_ID：基准数据集 ID（例如 SWE-bench/SWE-bench_Verified）。[必填]

选项：

• --limit INTEGER：限制结果数量。 [默认值：20]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf datasets leaderboard SWE-bench/SWE-bench_Verified $ hf datasets leaderboard SWE-bench/SWE-bench_Verified —limit 5 —format json $ hf datasets ls —filter benchmark:official # list available leaderboards

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf datasets list

列出 Hub 上的数据集，或数据集仓库中的文件。[别名：ls]

在不带参数调用时，列出 Hub 上的数据集。 在传入数据集 ID 时，列出该数据集仓库中的文件。

用法：

$ hf datasets list [OPTIONS] [REPO_ID]

参数：

• [REPO_ID]：数据集 ID（例如 username/repo-name），用于列出其中的文件。如果省略，则列出数据集。

选项：

• --search TEXT：搜索查询。
• --author TEXT：按作者或组织进行筛选。
• --filter TEXT：按标签筛选（例如 ‘text-classification’）。可多次使用。
• --sort [created_at|downloads|last_modified|likes|trending_score]：对结果进行排序。
• --limit INTEGER：限制结果数量。 [默认值：30]
• --expand TEXT：要返回的逗号分隔的属性。使用时，仅返回列出的属性（以及 id）。示例：‘—expand=downloads,likes,tags’。有效值：author, cardData, citation, createdAt, description, disabled, downloads, downloadsAllTime, gated, lastModified, likes, mainSize, paperswithcode_id, private, resourceGroup, sha, siblings, tags, trendingScore, usedStorage。
• -h, --human-readable：以人类可读的格式显示大小（仅适用于列出文件）。
• --tree：以树状格式列出文件（仅用于列出文件）。
• -R, --recursive：递归列出文件（仅用于列出文件）。
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf datasets ls $ hf datasets ls —sort downloads —limit 10 $ hf datasets ls —search “code” $ hf datasets ls —filter benchmark:official $ hf datasets ls HuggingFaceFW/fineweb $ hf datasets ls HuggingFaceFW/fineweb -R $ hf datasets ls HuggingFaceFW/fineweb —tree -h

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf datasets parquet

列出数据集中可用的 parquet 文件 URL。

用法：

$ hf datasets parquet [OPTIONS] DATASET_ID

参数：

• DATASET_ID：数据集 ID（例如 username/repo-name）。[必填]

选项：

• --subset TEXT：按 subset/config 筛选 parquet 条目。
• --split TEXT：按 split 筛选 parquet 条目。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf datasets parquet cfahlgren1/hub-stats $ hf datasets parquet cfahlgren1/hub-stats —subset models $ hf datasets parquet cfahlgren1/hub-stats —split train $ hf datasets parquet cfahlgren1/hub-stats —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf datasets sql

使用 DuckDB 针对数据集的 parquet URL 执行原始 SQL 查询。

用法：

$ hf datasets sql [OPTIONS] SQL

参数：

• SQL：要执行的原始 SQL 查询。 [必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf datasets sql “SELECT COUNT() AS rows FROM read_parquet(’https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet’)” $ hf datasets sql “SELECT FROM read_parquet(’https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet’) LIMIT 5” —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf 讨论

在 Hub 上管理讨论和拉取请求。

用法：

$ hf discussions [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• close：关闭讨论或拉取请求。
• comment：在讨论或拉取请求中发表评论。
• create：在仓库中创建新的讨论或拉取请求。
• diff：显示拉取请求的差异。
• edit：编辑讨论或拉取请求中已有的评论。
• info：获取讨论或拉取请求的信息。
• list：列出仓库中的讨论和拉取请求。[别名：ls]
• merge：合并拉取请求。
• rename：重命名讨论或拉取请求。
• reopen：重新打开已关闭的讨论或拉取请求。

关闭 hf discussions

关闭讨论或拉取请求。

用法：

$ hf discussions close [OPTIONS] REPO_ID NUM

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]

选项：

• --comment TEXT：关闭时发布的可选评论。
• -y, --yes：跳过确认提示。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions close username/my-model 5 $ hf discussions close username/my-model 5 —comment “Closing as resolved.”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions 评论

在讨论或拉取请求中发表评论。

用法：

$ hf discussions comment [OPTIONS] REPO_ID NUM

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]

选项：

• --body TEXT：评论文本（支持 Markdown）。
• --body-file PATH：从文件中读取注释。使用 ’-’ 表示标准输入。
• --attach TEXT：附加图像、视频或音频文件，格式为‘FILE’或‘FILE#alt text’。正文中的‘’引用将被替换为上传的文件，其他文件将被追加。可多次使用。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions comment username/my-model 5 —body “Thanks for reporting!” $ hf discussions comment username/my-model 5 —body “LGTM!” $ hf discussions comment username/my-model 5 —body “Here is a demo:” —attach demo.mp4

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions create

在仓库中创建新的讨论或拉取请求。

用法：

$ hf discussions create [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --title TEXT：讨论或拉取请求的标题。 [必填]
• --body TEXT：描述（支持 Markdown）。
• --body-file PATH：从文件中读取描述。使用 ’-’ 表示标准输入。
• --pull-request, --pr：创建拉取请求（pull request）而非讨论。
• --attach TEXT：附加图像、视频或音频文件，格式为‘FILE’或‘FILE#alt text’。正文中的‘’引用将被替换为上传的文件，其他文件将被追加。可多次使用。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions create username/my-model —title “Bug report” $ hf discussions create username/my-model —title “Feature request” —body “Please add X” $ hf discussions create username/my-model —title “Fix typo” —pull-request $ hf discussions create username/my-dataset —type dataset —title “Data quality issue” $ hf discussions create username/my-model —title “Fix rendering” —pr —attach “./before.png#Before the fix” —attach ./after.png

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions diff

显示拉取请求的 diff。

用法：

$ hf discussions diff [OPTIONS] REPO_ID NUM

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions diff username/my-model 5

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions 编辑

编辑讨论或拉取请求中现有的评论。

用法：

$ hf discussions edit [OPTIONS] REPO_ID NUM COMMENT_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]
• COMMENT_ID：要编辑的评论的 ID（参见 ‘hf discussions info … —format json’）。 [必填]

选项：

• --body TEXT：新的评论文本（支持 Markdown）。
• --body-file PATH：从文件中读取新评论。使用 ’-’ 表示标准输入。
• --attach TEXT：附加图像、视频或音频文件，格式为‘FILE’或‘FILE#alt text’。正文中的‘’引用将被替换为上传的文件，其他文件将被追加。可多次使用。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions edit username/my-model 5 abc123 —body “Updated comment.” $ hf discussions edit username/my-model 5 abc123 —body-file fixed.md $ hf discussions edit username/my-model 5 abc123 —body “Fixed: ” —attach ./after.png

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions info

获取讨论或拉取请求的信息。

用法：

$ hf discussions info [OPTIONS] REPO_ID NUM

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions info username/my-model 5 $ hf discussions info username/my-model 5 —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions list

列出仓库中的讨论和拉取请求。[别名：ls]

用法：

$ hf discussions list [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• -s, --status [open|closed|merged|draft|all]：按状态筛选（open、closed、merged、draft、all）。[默认值：open]
• -k, --kind [all|discussion|pull_request]：按类型（discussion、pull_request、all）进行筛选。 [默认值：all]
• --author TEXT：按作者或组织进行筛选。
• --limit INTEGER：限制结果数量。 [默认值：30]
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions list username/my-model $ hf discussions list username/my-model —kind pull_request —status merged $ hf discussions list username/my-dataset —type dataset —status closed $ hf discussions list username/my-model —author alice —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions 合并

合并拉取请求。

用法：

$ hf discussions merge [OPTIONS] REPO_ID NUM

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]

选项：

• --comment TEXT：合并时发布的可选评论。
• -y, --yes：跳过确认提示。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions merge username/my-model 5 $ hf discussions merge username/my-model 5 —comment “Merging, thanks!”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions 重命名

重命名讨论或拉取请求。

用法：

$ hf discussions rename [OPTIONS] REPO_ID NUM NEW_TITLE

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]
• NEW_TITLE：新标题。 [必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions rename username/my-model 5 “Updated title”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf discussions 重新开启

重新打开已关闭的讨论或拉取请求。

用法：

$ hf discussions reopen [OPTIONS] REPO_ID NUM

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• NUM：讨论或拉取请求的编号。[必填]

选项：

• --comment TEXT：重新打开时发布的可选评论。
• -y, --yes：跳过确认提示。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf discussions reopen username/my-model 5 $ hf discussions reopen username/my-model 5 —comment “Reopening for further investigation.”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf download

从 Hub 下载文件。

用法：

$ hf download [OPTIONS] REPO_ID [FILENAMES]...

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• [FILENAMES]...：要下载的文件（例如 config.json、data/metadata.jsonl）。

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：(model)]
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --include TEXT：用于指定要下载的文件的全局匹配模式。例如：*.json
• --exclude TEXT：用于从要下载的文件中排除的 Glob 模式。
• --cache-dir TEXT：用于保存文件的目录。
• --local-dir TEXT：如果设置，下载的文件将放置在此目录下。有关更多详细信息，请参阅 https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-a-local-folder。
• --force-download / --no-force-download：如果为 True，即使文件已缓存，也会重新下载。[默认值：no-force-download]
• --dry-run / --no-dry-run：如果为 True，则执行试运行，而不会实际下载文件。 [默认值：no-dry-run]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --max-workers INTEGER：用于下载文件的最大工作进程数。默认值为 8。 [默认值: 8]
• --help：显示此消息并退出。

示例 $ hf download meta-llama/Llama-3.2-1B-Instruct $ hf download meta-llama/Llama-3.2-1B-Instruct config.json tokenizer.json $ hf download meta-llama/Llama-3.2-1B-Instruct —include ”.safetensors” —exclude ”.bin” $ hf download meta-llama/Llama-3.2-1B-Instruct —local-dir ./models/llama $ hf download HuggingFaceM4/FineVision art/ —repo-type dataset $ hf download hf://datasets/HuggingFaceH4/ultrachat_200k

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints

管理 Hugging Face Inference Endpoints。

用法：

$ hf endpoints [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• catalog：与 Inference Endpoints 目录进行交互。
• delete：永久删除推理端点。
• deploy：从 Hub 仓库部署推理端点。
• describe：获取现有端点的信息。
• hardware：列出可用于部署推理端点的硬件。
• list：列出给定命名空间中的所有 Inference Endpoints。[别名：ls]
• list-catalog：列出模型目录中可用的模型。
• pause：暂停推理端点。
• resume：恢复推理端点。
• scale-to-zero：将推理端点缩容至零。
• update：更新现有端点。

hf endpoints 目录

与 Inference Endpoints 目录进行交互。

用法：

$ hf endpoints catalog [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• deploy：从模型目录部署推理端点。
• list：列出模型目录中可用的模型。[别名：ls]

hf endpoints catalog deploy

从模型目录部署推理端点。

目录模型通过配方进行部署：一种针对这些模型经过测试的硬件和引擎组合。 传入 —repo 以部署模型的默认配方，可选地通过 —accelerator 和 —gguf-file 进行细化，或者传入 —recipe 以部署由 hf endpoints catalog ls 列出的确切配方。

用法：

$ hf endpoints catalog deploy [OPTIONS]

选项：

• --repo TEXT：与 Inference Endpoint 关联的模型仓库名称（例如 ‘openai/gpt-oss-120b’）。将部署其默认配方。与 —recipe 互斥。
• --recipe TEXT：要部署的目录配方 ID，如 ‘hf endpoints catalog ls’ 所列。与 —repo 互斥。
• --name TEXT：端点名称。
• --accelerator [cpu|gpu|neuron]：用于推理的硬件加速器。仅在 —repo 下可用。
• --gguf-file TEXT：要部署的 GGUF 文件，适用于每种量化都有一个配方的模型。仅在 —repo 下可用。
• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints catalog deploy —repo meta-llama/Llama-3.2-1B-Instruct $ hf endpoints catalog deploy —recipe sizzling-biryani-g4xsi1ac

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints catalog list

列出模型目录中可用的模型。 [alias: ls]

每个配方对应一行，即每种经过测试的模型部署方式。使用 hf endpoints catalog deploy --recipe <RECIPE_ID> 部署其中一个。

用法：

$ hf endpoints catalog list [OPTIONS]

选项：

• --accelerator [cpu|gpu|neuron]：仅显示在此加速器上运行的配方。
• --engine [llamacpp|sglang|tei|vllm]：仅显示使用此推理引擎运行的配方。
• --license TEXT：仅显示使用此许可证的模型（例如 ‘Apache 2.0’）。
• --task TEXT：仅显示适用于此任务（例如 ‘text-generation’）的模型。
• --search TEXT：搜索查询。
• --limit INTEGER：限制返回的模型数量。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints catalog ls $ hf endpoints catalog ls —engine vllm

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints delete

永久删除推理端点。

用法：

$ hf endpoints delete [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --yes：跳过确认提示。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints delete my-endpoint

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints deploy

从 Hub 仓库部署推理端点。

运行 hf endpoints hardware 以列出有效的 --vendor、--region、--accelerator、--instance-type 和 --instance-size 组合。

用法：

$ hf endpoints deploy [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --repo TEXT：与推理端点关联的模型仓库名称（例如 ‘openai/gpt-oss-120b’）。 [必填]
• --framework TEXT：用于该模型的机器学习框架（例如 ‘vllm’）。[必填]
• --accelerator TEXT：用于推理的硬件加速器（例如 ‘cpu’）。 [必填]
• --instance-size TEXT：用于托管模型的实例大小或类型（例如 ‘x4’）。[必填]
• --instance-type TEXT：Inference Endpoint 将部署到的云实例类型（例如 ‘intel-icl’）。[必填]
• --region TEXT：将创建推理端点的云区域（例如 ‘us-east-1’）。[必填]
• --vendor TEXT：托管推理端点的云服务商或供应商（例如 'aws'）。[必填]
• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --task TEXT：要部署模型的任务（例如 ‘text-classification’）。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --min-replica INTEGER：Inference Endpoint 保持运行的最小副本（实例）数量。[默认值：1]
• --max-replica INTEGER：Inference Endpoint 可扩缩容到的最大副本（实例）数。[默认值：1]
• --scale-to-zero-timeout INTEGER：端点处于非活动状态后，缩容至零之前的等待时长（以分钟为单位）。
• --scaling-metric [pendingRequests|hardwareUsage]：用于扩缩容的指标参考。
• --scaling-threshold FLOAT：用于触发扩容的缩放指标阈值。在未提供缩放指标时，此参数将被忽略。
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --custom-image TEXT：用于运行容器的 Docker 镜像 URL（例如 ‘nexagi/sglang:v0.5.12’）。需要 ‘—framework custom’。
• --engine [custom|hf-serve|llamacpp|sglang|tei|tgi|tgi-neuron|vllm|vllm-neuron]：用于运行的托管引擎镜像——与 custom-image 搭配使用（例如 ‘vllm’）。默认使用任意容器。
• --health-route TEXT：容器暴露的健康检查路由（例如 ‘/health’）。需要 —custom-image。
• --port INTEGER：容器监听的端口（例如 30000）。需要 —custom-image。
• --container-registry-username TEXT：用于对托管 —custom-image 的注册表进行身份验证的用户名。
• --container-registry-password TEXT：用于对托管 —custom-image 的注册表进行身份验证的可选密码。
• --tensor-parallel-size INTEGER：用于将单个模型副本分片到多少个加速器上（仅适用于 vLLM 和 SGLang 引擎）。
• --data-parallel-size INTEGER：要运行的模型副本数量，每个加速器一个（仅限 vLLM 引擎）。
• --container-command TEXT：覆盖容器的入口点，以引号包裹的字符串形式提供，并拆分为多个标记（例如 “python -m sglang.launch_server”）。
• --container-args TEXT：附加到容器入口点的参数，以引号字符串形式提供并拆分为多个标记（例如 “—tp 8 —reasoning-parser qwen3”）。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• --type [public|authenticated|private]：端点访问类型。默认为 ‘authenticated’（需要令牌，可公开访问）。
• --help：显示此消息并退出。

示例 $ hf endpoints deploy my-endpoint —repo gpt2 —framework pytorch … $ hf endpoints deploy my-endpoint —repo openai/gpt-oss-120b —framework custom —engine vllm —custom-image vllm/vllm-openai:v0.23.0 —tensor-parallel-size 8 …

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints describe

获取现有端点的信息。

用法：

$ hf endpoints describe [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints describe my-endpoint

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints 硬件

列出可用于部署推理端点的硬件。

当前仅列出该命名空间可部署的硬件：状态可用，且加速器配额足以支持一个副本。使用 --all 可列出 API 返回的所有组合。

配额是按命名空间计算的，因此请传入与 hf endpoints deploy 相同的 --namespace。价格以美元为单位，按每个副本每小时计算。

用法：

$ hf endpoints hardware [OPTIONS]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --vendor TEXT：仅显示由该云服务商托管的硬件（例如 ‘aws’）。
• --region TEXT：仅显示此云区域中可用的硬件（例如 ‘us-east-1’）。
• --accelerator TEXT：仅显示具有此加速器的硬件（例如 ‘cpu’、‘gpu’、‘neuron’）。
• --instance-type TEXT：仅显示此实例类型的硬件（例如 ‘nvidia-l4’）。
• -a, --all：同时显示当前无法部署的硬件（不可用、已弃用或超出配额）。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints hardware $ hf endpoints hardware —vendor aws —accelerator gpu

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints list

列出给定命名空间中的所有 Inference Endpoints。[别名: ls]

用法：

$ hf endpoints list [OPTIONS]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints ls $ hf endpoints ls —namespace my-org

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints list-catalog

列出模型目录中可用的模型。

每个配方对应一行，即每种经过测试的模型部署方式。使用 hf endpoints catalog deploy --recipe <RECIPE_ID> 部署其中一个。

用法：

$ hf endpoints list-catalog [OPTIONS]

选项：

• --accelerator [cpu|gpu|neuron]：仅显示在此加速器上运行的配方。
• --engine [llamacpp|sglang|tei|vllm]：仅显示使用此推理引擎运行的配方。
• --license TEXT：仅显示使用此许可证的模型（例如 ‘Apache 2.0’）。
• --task TEXT：仅显示适用于此任务（例如 ‘text-generation’）的模型。
• --search TEXT：搜索查询。
• --limit INTEGER：限制返回的模型数量。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

hf endpoints pause

暂停推理端点。

用法：

$ hf endpoints pause [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints pause my-endpoint

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints resume

恢复推理端点。

用法：

$ hf endpoints resume [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --fail-if-already-running：如果 True，当 Inference Endpoint 已在运行时，该方法将引发错误。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints resume my-endpoint

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints scale-to-zero

将推理端点缩容至零。

用法：

$ hf endpoints scale-to-zero [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints scale-to-zero my-endpoint

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf endpoints update

更新现有端点。

用法：

$ hf endpoints update [OPTIONS] NAME

参数：

• NAME：端点名称。 [必填]

选项：

• --namespace TEXT：与 Inference Endpoint 关联的命名空间。默认值为当前用户的命名空间。
• --repo TEXT：与 Inference Endpoint 关联的模型仓库名称（例如 ‘openai/gpt-oss-120b’）。
• --accelerator TEXT：用于推理的硬件加速器（例如 ‘cpu’）。
• --instance-size TEXT：用于托管模型的实例大小或类型（例如 ‘x4’）。
• --instance-type TEXT：Inference Endpoint 将部署到的云实例类型（例如 ‘intel-icl’）。
• --framework TEXT：用于该模型的机器学习框架（例如 ‘custom’）。
• --revision TEXT：要在 Inference Endpoint 上部署的特定模型修订版本（例如 ‘6c0e6080953db56375760c0471a8c5f2929baf11’）。
• --task TEXT：要部署模型的任务（例如 ‘text-classification’）。
• --custom-image TEXT：用于运行容器的 Docker 镜像 URL（例如 ‘nexagi/sglang:v0.5.12’）。这会替换端点上当前配置的镜像，而不是对其进行修补，因此请同时传入您希望保留的引擎和容器设置，并先运行 ‘hf endpoints describe NAME’ 以查看这些设置。
• --engine [custom|hf-serve|llamacpp|sglang|tei|tgi|tgi-neuron|vllm|vllm-neuron]：用于运行的托管引擎镜像——与 custom-image 搭配使用（例如 ‘vllm’）。默认使用任意容器。
• --health-route TEXT：容器暴露的健康检查路由（例如 ‘/health’）。需要 —custom-image。
• --port INTEGER：容器监听的端口（例如 30000）。需要 —custom-image。
• --tensor-parallel-size INTEGER：用于将单个模型副本分片到多少个加速器上（仅适用于 vLLM 和 SGLang 引擎）。
• --data-parallel-size INTEGER：要运行的模型副本数量，每个加速器一个（仅限 vLLM 引擎）。
• --container-command TEXT：覆盖容器的入口点，以引号包裹的字符串形式提供，并拆分为多个标记（例如 “python -m sglang.launch_server”）。此操作会替换当前值；传入空字符串可将其清除。
• --container-args TEXT：附加到容器入口点的参数，以引号字符串形式提供并按空格拆分为多个标记（例如 “—enable-auto-tool-choice —tool-call-parser lfm2”）。此参数会替换端点当前已设置的参数，而不是追加，因此请包含您希望保留的参数；建议先运行 ‘hf endpoints describe NAME’ 查看当前参数。传入空字符串可清除这些参数。
• --min-replica INTEGER：Inference Endpoint 保持运行的最小副本（实例）数量。
• --max-replica INTEGER：Inference Endpoint 可扩缩容到的最大副本（实例）数量。
• --scale-to-zero-timeout INTEGER：端点处于非活动状态后，缩容至零之前的等待时长（以分钟为单位）。
• --scaling-metric [pendingRequests|hardwareUsage]：用于扩缩容的指标参考。
• --scaling-threshold FLOAT：用于触发扩容的缩放指标阈值。在未提供缩放指标时，此参数将被忽略。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf endpoints update my-endpoint —min-replica 2 $ hf endpoints update my-endpoint —tensor-parallel-size 8 $ hf endpoints update my-endpoint —container-args “—enable-auto-tool-choice —tool-call-parser lfm2”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf env

打印有关环境的信息。

用法：

$ hf env [OPTIONS]

选项：

• --help：显示此消息并退出。

hf 扩展

管理 hf CLI 扩展。[别名: ext]

安全警告：扩展是第三方可执行文件或 Python 包。请仅从您信任的来源安装。

用法：

$ hf extensions [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• exec：执行已安装的扩展。
• install：从公共 GitHub 仓库安装扩展。
• list：列出已安装的扩展命令。[别名：ls]
• remove：移除已安装的扩展。[别名：rm]
• search：搜索 GitHub 上可用的扩展（带有 ‘hf-extension’ 主题标签）。
• update：将已安装的扩展更新到最新版本。

hf extensions exec

执行已安装的扩展。

用法：

$ hf extensions exec [OPTIONS] NAME

参数：

• NAME：扩展名称（可带或不带 hf- 前缀）。[必填]

选项：

• --help：显示此消息并退出。

示例 $ hf extensions exec claude — —help $ hf extensions exec claude —model zai-org/GLM-5

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf extensions install

从公共 GitHub 仓库安装扩展。

安全警告：此操作将安装第三方可执行文件或 Python 包。 请仅从您信任的来源进行安装。

用法：

$ hf extensions install [OPTIONS] REPO_ID

参数：

• REPO_ID：采用 [OWNER/]hf-<name> 格式的 GitHub 扩展仓库。 [必填]

选项：

• --force：如果已安装，则覆盖。
• --help：显示此消息并退出。

示例 $ hf extensions install hf-claude $ hf extensions install hanouticelina/hf-claude $ hf extensions install alvarobartt/hf-mem

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf extensions list

列出已安装的扩展命令。[别名: ls]

用法：

$ hf extensions list [OPTIONS]

选项：

• --help：显示此消息并退出。

示例 $ hf extensions list

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf extensions remove

删除已安装的扩展。[别名: rm]

用法：

$ hf extensions remove [OPTIONS] NAME

参数：

• NAME：要删除的扩展名称（带或不带 hf- 前缀）。[必填]

选项：

• --help：显示此消息并退出。

示例 $ hf extensions remove claude

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf extensions search

搜索在 GitHub 上可用的扩展（带有 ‘hf-extension’ 主题标签）。

用法：

$ hf extensions search [OPTIONS]

选项：

• --help：显示此消息并退出。

示例 $ hf extensions search

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf extensions update

将已安装的扩展更新到最新版本。

用法：

$ hf extensions update [OPTIONS] [NAME]

参数：

• [NAME]：要更新的扩展（带或不带 hf- 前缀，可选格式为 OWNER/hf-<name>）。如果省略，则会检查所有已安装的扩展并更新过时的扩展。

选项：

• --help：显示此消息并退出。

示例 $ hf extensions update $ hf extensions update hf-claude $ hf extensions update alvarobartt/hf-mem

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs

在 Hub 上运行和管理 Jobs。

用法：

$ hf jobs [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• cancel：取消任务
• expose：替换正在运行的 Job 上已暴露的端口。
• hardware：列出作业可用的硬件选项
• inspect：显示一个或多个 Job 的详细信息
• labels：更新 Job 的标签。
• list：列出任务。[别名：ls, ps]
• logs：获取 Job 的日志。
• rerun：使用现有 Job 的 spec 运行新的 Job。
• run：运行一个 Job。
• scheduled：在 Hub 上创建和管理计划任务。
• ssh：SSH 连接到正在运行的 Job。
• stats：获取作业的资源使用统计信息和指标。
• uv：在 HF 基础设施上运行 UV 脚本（带有内联依赖项的 Python）。
• wait：等待一个或多个 Job 到达终止状态。

hf jobs cancel

取消任务

用法：

$ hf jobs cancel [OPTIONS] JOB_ID

参数：

• JOB_ID：作业 ID（或 ‘namespace/job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs cancel <job_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs 公开

替换正在运行的 Job 上暴露的端口。

用法：

$ hf jobs expose [OPTIONS] JOB_ID [PORTS]...

参数：

• JOB_ID：作业 ID（或 ‘namespace/job_id’） [必填]
• [PORTS]...：要通过作业代理暴露的端口。访问需要具有该作业命名空间读取权限的 HF token。

选项：

• --public INTEGER：公开一个端口，无需身份验证。如需公开多个端口，请重复使用该标志。无需再将端口作为位置参数传入。
• --clear：关闭所有已暴露的端口。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs expose <job_id> 8000 $ hf jobs expose <job_id> 8000 —public 9000 $ hf jobs expose <job_id> —clear

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs hardware

列出作业可用的硬件选项

用法：

$ hf jobs hardware [OPTIONS]

选项：

• --help：显示此消息并退出。

示例 $ hf jobs hardware

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs inspect

显示一个或多个 Job 的详细信息

用法：

$ hf jobs inspect [OPTIONS] JOB_IDS...

参数：

• JOB_IDS...：要检查的作业 ID（或 ‘namespace/job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs inspect <job_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs labels

更新 Job 的标签。传入 —label 会替换所有现有标签；仅传入 —name 则会保留现有标签。

用法：

$ hf jobs labels [OPTIONS] JOB_ID

参数：

• JOB_ID：作业 ID（或 ‘namespace/job_id’） [必填]

选项：

• --name TEXT：为 Job 命名。存储为 name 标签。名称无需唯一。默认值为镜像或脚本名称加上解析后的启动配置的简短哈希值。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• --clear：从任务中移除所有标签。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs labels <job_id> —name training-v2 $ hf jobs labels <job_id> —label env=prod —label team=ml $ hf jobs labels <job_id> —clear

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs list | ls | ps

列出任务。

使用 --status 按状态进行筛选（可能的值参见 JobStage），使用 --label 按 key=value 标签进行筛选。Job 必须匹配所有筛选条件才会被列出。

用法：

$ hf jobs list | ls | ps [OPTIONS]

选项：

• -a, --all：显示所有任务（默认显示正在运行和调度中的任务）。不能与 —status 一起使用。
• --status [COMPLETED|CANCELED|ERROR|DELETED|SCHEDULING|RUNNING]：仅显示具有指定状态的 Jobs。支持逗号分隔或重复指定，例如 --status running,scheduling。
• -l, --label TEXT：仅显示带有指定 key=value 标签的 Jobs。可重复使用以要求多个标签，例如 --label env=prod --label team=ml。
• --name TEXT：仅显示具有指定名称的 Jobs（--label name=NAME 的快捷方式）。
• --limit INTEGER：要显示的最大 Job 数量。设置为 0 表示显示全部（无限制）。[默认值：100]
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs ls $ hf jobs ls -a $ hf jobs ls —status running,scheduling $ hf jobs ls —name training-v2 $ hf jobs ls —label env=prod —label team=ml $ hf jobs ls —all —label hf-sandbox=1

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs logs

获取 Job 的日志。

默认情况下，打印当前可用的日志并退出（非阻塞）。 使用 —follow/-f 以流式方式实时输出日志，直到作业完成。 使用 —tail/-n 限制返回的行数（在受支持的情况下，在服务器端执行）。

注意：日志流结束后，以下操作将退出，无论 Job 是成功还是失败。运行 hf jobs inspect <job_id> 以检查最终状态。

用法：

$ hf jobs logs [OPTIONS] JOB_ID

参数：

• JOB_ID：作业 ID（或 ‘namespace/job_id’） [必填]

选项：

• -f, --follow：跟踪日志输出（持续流式输出直至任务完成）。如果不使用此标志，则仅打印当前可用的日志。
• -n, --tail INTEGER：显示日志末尾的行数。与 —follow 结合使用时，从最后 N 行开始流式传输。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs logs <job_id> $ hf jobs logs -f <job_id> $ hf jobs logs —tail 20 <job_id> $ hf jobs logs -f —tail 100 <job_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs rerun

使用现有 Job 的 spec 运行新的 Job。

用法：

$ hf jobs rerun [OPTIONS] JOB_ID

参数：

• JOB_ID：作业 ID（或 ‘namespace/job_id’） [必填]

选项：

• -d, --detach：在后台运行 Job 并打印 Job ID。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs rerun <job_id> $ hf jobs rerun —detach <job_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs run

运行任务。

用法：

$ hf jobs run [OPTIONS] IMAGE COMMAND...

参数：

• IMAGE：要使用的 Docker 镜像。 [必填]
• COMMAND...：要运行的命令。 [必填]

选项：

• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --name TEXT：为 Job 命名。存储为 name 标签。名称无需唯一。默认值为镜像或脚本名称加上解析后的启动配置的简短哈希值。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro|:rw] 或 LOCAL_DIR:/MOUNT_PATH[:ro|:rw]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认以读写方式挂载。本地目录源会先同步到 bucket，并默认以只读方式挂载。例如 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro 或 -v ./inputs:/inputs
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：硬件的规格。运行 ‘hf jobs hardware’ 以列出可用的规格。默认为 cpu-basic。
• --timeout TEXT：最大持续时间：带 s（秒，默认值）、m（分钟）、h（小时）或 d（天）的整数。
• --attempts INTEGER RANGE：最大尝试次数，包括首次运行。默认为 1。 [x>=1]
• -d, --detach：在后台运行 Job 并打印 Job ID。
• --dry-run：打印解析后的 Job 配置，但不提交 Job。
• --expose INTEGER：通过作业代理暴露容器端口。如需暴露多个端口，请重复使用该标志（例如 --expose 8000 --expose 8001）。每个暴露的端口均可通过公共作业域名访问；访问需要具有该作业命名空间读取权限的 HF token。
• --expose-public INTEGER：通过作业代理公开容器端口，且无需身份验证。如需公开多个端口，请重复使用该标志。无需同时通过 --expose 传递端口。
• --ssh：使任务的容器可通过 SSH 访问。使用 hf jobs ssh <job_id> 进行连接。需要在 https://huggingface.co/settings/keys 上注册 SSH 公钥。
• --network-group TEXT：加入一个网络组。同一命名空间和资源组中共享同一组的作业会被放置在一起，并可在所有端口上相互访问。在每个成员内部，$HF_NETWORK_GROUP_HOSTNAME 会解析到所有成员。仅允许小写字母、数字和连字符，最多 46 个字符。
• --network-alias TEXT：在网络组中声明一个别名。组内成员可通过 ${HF_NETWORK_GROUP_PREFIX}<alias> 访问声明了该别名的任务。可重复使用此标志以声明多个别名。别名仅允许小写字母、数字和连字符，最长 34 个字符，且在任务内必须唯一。需要配合 --network-group 使用。
• --resource-group-id TEXT：用于创建 Job 的资源组 ID。用于控制组织内资源的访问权限，以及成本归属/支出限制功能。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --format [agent|auto|human|json|quiet]：输出格式。默认为 ‘auto’，会根据终端自动选择 ‘agent’ 或 ‘human’。
• --json：JSON 输出。等同于 ‘—format json’。
• -q, --quiet：安静输出（每行一个 ID）。等同于 ‘—format quiet’。
• --help：显示此消息并退出。

示例 $ hf jobs run —name hello-world python:3.12 python -c ‘print(“Hello!”)’ $ hf jobs run —detach python:3.12 python script.py $ hf jobs run -e FOO=foo python:3.12 python script.py $ hf jobs run —secrets HF_TOKEN python:3.12 python script.py $ hf jobs run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt python:3.12 python script.py

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled

在 Hub 上创建和管理计划任务（Jobs）。

用法：

$ hf jobs scheduled [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• delete：删除已调度的 Job。
• inspect：显示一个或多个已调度 Job 的详细信息
• labels：更新已调度 Job 的标签。
• list：列出已调度的 Job。[别名：ls, ps]
• reschedule：更改已计划 Job 的运行时间。
• resume：恢复（取消暂停）已调度的 Job。
• run：调度一个 Job。
• suspend：暂停已调度的 Job。
• trigger：立即触发已调度的 Job 运行（不更改调度计划）。
• uv：在 HF 基础设施上调度 UV 脚本。

hf jobs scheduled delete

删除已调度的 Job。

用法：

$ hf jobs scheduled delete [OPTIONS] SCHEDULED_JOB_ID

参数：

• SCHEDULED_JOB_ID：计划任务 ID（或 ‘namespace/scheduled_job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled delete <id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled inspect

显示一个或多个已调度作业的详细信息

用法：

$ hf jobs scheduled inspect [OPTIONS] SCHEDULED_JOB_IDS...

参数：

• SCHEDULED_JOB_IDS...：要检查的定时任务 ID（或 ‘namespace/scheduled_job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled inspect <id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled labels

更新计划任务（Job）的标签。传入 —label 会替换所有现有标签；仅传入 —name 则会保留现有标签。

用法：

$ hf jobs scheduled labels [OPTIONS] SCHEDULED_JOB_ID

参数：

• SCHEDULED_JOB_ID：计划任务 ID（或 ‘namespace/scheduled_job_id’） [必填]

选项：

• --name TEXT：为 Job 命名。存储为 name 标签。名称无需唯一。默认值为镜像或脚本名称加上解析后的启动配置的简短哈希值。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• --clear：从计划任务中移除所有标签。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled labels <id> —name daily-script $ hf jobs scheduled labels <id> —label env=prod —label team=ml $ hf jobs scheduled labels <id> —clear

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled list | ls | ps

列出已调度的作业。

使用 --status 按状态（active 或 suspended）进行筛选，使用 --label 按 key=value 标签进行筛选。 计划任务必须匹配所有筛选条件才会被列出。

用法：

$ hf jobs scheduled list | ls | ps [OPTIONS]

选项：

• -a, --all：显示所有已调度的 Job（默认隐藏已挂起的）。不能与 —status 一起使用。
• --status [active|suspended]：仅显示具有指定状态的已调度 Job。支持逗号分隔或重复使用，例如 --status suspended。
• -l, --label TEXT：仅显示带有指定 key=value 标签的已调度 Job。可重复使用以要求多个标签，例如 --label env=prod --label team=ml。
• --name TEXT：仅显示具有指定名称的已调度 Job（--label name=NAME 的快捷方式）。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled ls $ hf jobs scheduled ls -a $ hf jobs scheduled ls —status suspended $ hf jobs scheduled ls —name daily-script $ hf jobs scheduled ls —label env=prod —label team=ml

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled reschedule

更改计划任务（Job）的运行时间。

用法：

$ hf jobs scheduled reschedule [OPTIONS] SCHEDULED_JOB_ID SCHEDULE

参数：

• SCHEDULED_JOB_ID：计划任务 ID（或 ‘namespace/scheduled_job_id’） [必填]
• SCHEDULE：@annually、@yearly、@monthly、@weekly、@daily、@hourly 之一，或一个 CRON 调度表达式。[必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled reschedule <id> “0 9 * * 1”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled resume

恢复（取消暂停）已调度的 Job。

用法：

$ hf jobs scheduled resume [OPTIONS] SCHEDULED_JOB_ID

参数：

• SCHEDULED_JOB_ID：计划任务 ID（或 ‘namespace/scheduled_job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled resume <id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled run

调度任务。

用法：

$ hf jobs scheduled run [OPTIONS] SCHEDULE IMAGE COMMAND...

参数：

• SCHEDULE：@annually、@yearly、@monthly、@weekly、@daily、@hourly 之一，或一个 CRON 调度表达式。[必填]
• IMAGE：要使用的 Docker 镜像。 [必填]
• COMMAND...：要运行的命令。 [必填]

选项：

• --suspend / --no-suspend：暂停已调度的 Job
• --concurrency / --no-concurrency：允许此 Job 的多个实例并发运行
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --name TEXT：为 Job 命名。存储为 name 标签。名称无需唯一。默认值为镜像或脚本名称加上解析后的启动配置的简短哈希值。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro|:rw] 或 LOCAL_DIR:/MOUNT_PATH[:ro|:rw]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认以读写方式挂载。本地目录源会先同步到 bucket，并默认以只读方式挂载。例如 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro 或 -v ./inputs:/inputs
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：硬件的规格。运行 ‘hf jobs hardware’ 以列出可用的规格。默认为 cpu-basic。
• --timeout TEXT：最大持续时间：带 s（秒，默认值）、m（分钟）、h（小时）或 d（天）的整数。
• --attempts INTEGER RANGE：最大尝试次数，包括首次运行。默认为 1。 [x>=1]
• --dry-run：打印解析后的 Job 配置，但不提交 Job。
• --expose INTEGER：通过作业代理暴露容器端口。如需暴露多个端口，请重复使用该标志（例如 --expose 8000 --expose 8001）。每个暴露的端口均可通过公共作业域名访问；访问需要具有该作业命名空间读取权限的 HF token。
• --expose-public INTEGER：通过作业代理公开容器端口，且无需身份验证。如需公开多个端口，请重复使用该标志。无需同时通过 --expose 传递端口。
• --resource-group-id TEXT：用于创建 Job 的资源组 ID。用于控制组织内资源的访问权限，以及成本归属/支出限制功能。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --format [agent|auto|human|json|quiet]：输出格式。默认为 ‘auto’，会根据终端自动选择 ‘agent’ 或 ‘human’。
• --json：JSON 输出。等同于 ‘—format json’。
• -q, --quiet：安静输出（每行一个 ID）。等同于 ‘—format quiet’。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled run “0 0 * * *” —name daily-script python:3.12 python script.py

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled suspend

暂停已调度的 Job。

用法：

$ hf jobs scheduled suspend [OPTIONS] SCHEDULED_JOB_ID

参数：

• SCHEDULED_JOB_ID：计划任务 ID（或 ‘namespace/scheduled_job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled suspend <id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled trigger

触发计划任务立即运行（不会更改计划）。

用法：

$ hf jobs scheduled trigger [OPTIONS] SCHEDULED_JOB_ID

参数：

• SCHEDULED_JOB_ID：计划任务 ID（或 ‘namespace/scheduled_job_id’） [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled trigger <id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs scheduled uv

在 HF 基础设施上调度 UV 脚本。

用法：

$ hf jobs scheduled uv [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• run：在 HF 基础设施上运行 UV 脚本（本地文件或 URL）

hf jobs scheduled uv run

在 HF 基础设施上运行 UV 脚本（本地文件或 URL）

用法：

$ hf jobs scheduled uv run [OPTIONS] SCHEDULE SCRIPT [SCRIPT_ARGS]...

参数：

• SCHEDULE：@annually、@yearly、@monthly、@weekly、@daily、@hourly 之一，或一个 CRON 调度表达式。[必填]
• SCRIPT：要运行的 UV 脚本（本地文件或 URL） [必填]
• [SCRIPT_ARGS]...：脚本的参数

选项：

• --suspend / --no-suspend：暂停已调度的 Job
• --concurrency / --no-concurrency：允许此 Job 的多个实例并发运行
• --image TEXT：使用已安装 uv 的自定义 Docker 镜像。
• --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：硬件的规格。运行 ‘hf jobs hardware’ 以列出可用的规格。默认为 cpu-basic。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --name TEXT：为 Job 命名。存储为 name 标签。名称无需唯一。默认值为镜像或脚本名称加上解析后的启动配置的简短哈希值。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro|:rw] 或 LOCAL_DIR:/MOUNT_PATH[:ro|:rw]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认以读写方式挂载。本地目录源会先同步到 bucket，并默认以只读方式挂载。例如 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro 或 -v ./inputs:/inputs
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• --timeout TEXT：最大持续时间：带 s（秒，默认值）、m（分钟）、h（小时）或 d（天）的整数。
• --attempts INTEGER RANGE：最大尝试次数，包括首次运行。默认为 1。 [x>=1]
• --dry-run：打印解析后的 Job 配置，但不提交 Job。
• --expose INTEGER：通过作业代理暴露容器端口。如需暴露多个端口，请重复使用该标志（例如 --expose 8000 --expose 8001）。每个暴露的端口均可通过公共作业域名访问；访问需要具有该作业命名空间读取权限的 HF token。
• --expose-public INTEGER：通过作业代理公开容器端口，且无需身份验证。如需公开多个端口，请重复使用该标志。无需同时通过 --expose 传递端口。
• --resource-group-id TEXT：用于创建 Job 的资源组 ID。用于控制组织内资源的访问权限，以及成本归属/支出限制功能。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --with TEXT：在安装了指定软件包的情况下运行
• -p, --python TEXT：用于运行环境的 Python 解释器
• --format [agent|auto|human|json|quiet]：输出格式。默认为 ‘auto’，会根据终端自动选择 ‘agent’ 或 ‘human’。
• --json：JSON 输出。等同于 ‘—format json’。
• -q, --quiet：安静输出（每行一个 ID）。等同于 ‘—format quiet’。
• --help：显示此消息并退出。

示例 $ hf jobs scheduled uv run “0 0 * * ” —name daily-script script.py $ hf jobs scheduled uv run “0 0 * *” script.py —with pandas

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs ssh

通过 SSH 连接到正在运行的 Job。

如果 Job 尚未运行，则等待其进入 RUNNING 状态后再进行连接。要求 Job 在启动时已启用 SSH（hf jobs run --ssh ...），并且您的 SSH 公钥已在 https://huggingface.co/settings/keys 处注册。

用法：

$ hf jobs ssh [OPTIONS] JOB_ID

参数：

• JOB_ID：作业 ID（或 ‘namespace/job_id’） [必填]

选项：

• -i, --identity-file PATH：SSH 身份文件的路径（转发给 ssh -i）。
• --dry-run：打印 SSH 命令而不是执行它。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs ssh <job_id> $ hf jobs ssh <job_id> —dry-run $ hf jobs ssh <job_id> -i ~/.ssh/id_ed25519

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs stats

获取作业的资源使用统计信息和指标。

默认情况下，打印当前统计信息的快照并退出（非阻塞）。 使用 —follow/-f 以实时显示统计信息，直到任务完成。

用法：

$ hf jobs stats [OPTIONS] [JOB_IDS]...

参数：

• [JOB_IDS]...：作业 ID（或“namespace/job_id”）

选项：

• -f, --follow：跟踪统计输出（实时视图，直到任务完成）。如果不使用此标志，则只打印一次快照。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs stats $ hf jobs stats <job_id> $ hf jobs stats -f <job_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs uv

在 HF 基础设施上运行 UV 脚本（带有内联依赖项的 Python）。

用法：

$ hf jobs uv [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• run：在 HF 基础设施上运行 UV 脚本（本地文件或 URL）

hf jobs uv run

在 HF 基础设施上运行 UV 脚本（本地文件或 URL）

用法：

$ hf jobs uv run [OPTIONS] SCRIPT [SCRIPT_ARGS]...

参数：

• SCRIPT：要运行的 UV 脚本（本地文件或 URL） [必填]
• [SCRIPT_ARGS]...：脚本的参数

选项：

• --image TEXT：使用已安装 uv 的自定义 Docker 镜像。
• --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：硬件的规格。运行 ‘hf jobs hardware’ 以列出可用的规格。默认为 cpu-basic。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --name TEXT：为 Job 命名。存储为 name 标签。名称无需唯一。默认值为镜像或脚本名称加上解析后的启动配置的简短哈希值。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro|:rw] 或 LOCAL_DIR:/MOUNT_PATH[:ro|:rw]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认以读写方式挂载。本地目录源会先同步到 bucket，并默认以只读方式挂载。例如 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro 或 -v ./inputs:/inputs
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• --timeout TEXT：最大持续时间：带 s（秒，默认值）、m（分钟）、h（小时）或 d（天）的整数。
• --attempts INTEGER RANGE：最大尝试次数，包括首次运行。默认为 1。 [x>=1]
• -d, --detach：在后台运行 Job 并打印 Job ID。
• --dry-run：打印解析后的 Job 配置，但不提交 Job。
• --expose INTEGER：通过作业代理暴露容器端口。如需暴露多个端口，请重复使用该标志（例如 --expose 8000 --expose 8001）。每个暴露的端口均可通过公共作业域名访问；访问需要具有该作业命名空间读取权限的 HF token。
• --expose-public INTEGER：通过作业代理公开容器端口，且无需身份验证。如需公开多个端口，请重复使用该标志。无需同时通过 --expose 传递端口。
• --ssh：使任务的容器可通过 SSH 访问。使用 hf jobs ssh <job_id> 进行连接。需要在 https://huggingface.co/settings/keys 上注册 SSH 公钥。
• --network-group TEXT：加入一个网络组。同一命名空间和资源组中共享同一组的作业会被放置在一起，并可在所有端口上相互访问。在每个成员内部，$HF_NETWORK_GROUP_HOSTNAME 会解析到所有成员。仅允许小写字母、数字和连字符，最多 46 个字符。
• --network-alias TEXT：在网络组中声明一个别名。组内成员可通过 ${HF_NETWORK_GROUP_PREFIX}<alias> 访问声明了该别名的任务。可重复使用此标志以声明多个别名。别名仅允许小写字母、数字和连字符，最长 34 个字符，且在任务内必须唯一。需要配合 --network-group 使用。
• --resource-group-id TEXT：用于创建 Job 的资源组 ID。用于控制组织内资源的访问权限，以及成本归属/支出限制功能。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --with TEXT：在安装了指定软件包的情况下运行
• -p, --python TEXT：用于运行环境的 Python 解释器
• --format [agent|auto|human|json|quiet]：输出格式。默认为 ‘auto’，会根据终端自动选择 ‘agent’ 或 ‘human’。
• --json：JSON 输出。等同于 ‘—format json’。
• -q, --quiet：安静输出（每行一个 ID）。等同于 ‘—format quiet’。
• --help：显示此消息并退出。

示例 $ hf jobs uv run —name my-script my_script.py $ hf jobs uv run —detach my_script.py $ hf jobs uv run —flavor a10g-small ml_training.py $ hf jobs uv run —with transformers train.py $ hf jobs uv run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt script.py $ hf jobs uv run —dry-run script.py

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf jobs wait

等待一个或多个 Job 达到终止状态。

阻塞直到所有 Job 完成，然后退出：如果所有 Job 均成功完成，则退出码为 0；如果任何 Job 被取消、出错或被删除，则返回非零退出码。

所有 Job 必须属于同一个命名空间。

用法：

$ hf jobs wait [OPTIONS] JOB_IDS...

参数：

• JOB_IDS...：要等待的作业 ID（或 ‘namespace/job_id’）。 [必填]

选项：

• --timeout TEXT：最大等待时间：int，单位为 s（秒，默认）、m（分钟）、h（小时）或 d（天）。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf jobs wait <job_id> $ hf jobs wait <job_id_1> <job_id_2> $ hf jobs ls -q | xargs hf jobs wait

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf lfs-enable-largefiles

配置您的仓库以启用上传大于 5GB 的文件。

此命令配置 git-lfs 使用自定义的多部分传输代理，从而支持将大文件分块高效上传。

用法：

$ hf lfs-enable-largefiles [OPTIONS] PATH

参数：

• PATH：要配置的仓库的本地路径。[必填]

选项：

• --help：显示此消息并退出。

hf lfs-multipart-upload

用于分块上传的内部 git-lfs 自定义传输代理。

此函数实现了用于 git-lfs 分块上传的自定义传输协议。 处理向 Hugging Face Hub 分块上传大文件。

用法：

$ hf lfs-multipart-upload [OPTIONS]

选项：

• --help：显示此消息并退出。

hf models

与 Hub 上的模型进行交互。

用法：

$ hf models [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• card：获取 Hub 上某个模型对应的模型卡片（README）。
• info：获取 Hub 上某个模型的信息。
• list：列出 Hub 上的模型，或模型仓库中的文件。[别名：ls]

hf models card

获取 Hub 上某个模型的模型卡（README）。

用法：

$ hf models card [OPTIONS] MODEL_ID

参数：

• MODEL_ID：模型 ID（例如 username/repo-name）。[必填]

选项：

• --metadata：仅输出卡片中的元数据。
• --text：仅输出文本正文（不包含元数据）。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf models card google/gemma-4-31B-it $ hf models card google/gemma-4-31B-it —metadata $ hf models card google/gemma-4-31B-it —metadata —format json $ hf models card google/gemma-4-31B-it —text

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf models info

获取 Hub 上某个模型的信息。

用法：

$ hf models info [OPTIONS] MODEL_ID

参数：

• MODEL_ID：模型 ID（例如 username/repo-name）。[必填]

选项：

• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --expand TEXT：要返回的逗号分隔的属性。使用时，仅返回列出的属性（以及 id）。示例：‘—expand=downloads,likes,tags’。有效值：author, baseModels, cardData, childrenModelCount, config, createdAt, disabled, downloads, downloadsAllTime, evalResults, gated, gguf, inference, inferenceProviderMapping, lastModified, library_name, likes, mask_token, model-index, pipeline_tag, private, resourceGroup, safetensors, sha, siblings, spaces, tags, transformersInfo, trendingScore, usedStorage, widgetData。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf models info meta-llama/Llama-3.2-1B-Instruct $ hf models info Qwen/Qwen3.5-9B —expand downloads,likes,tags

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf models list

列出 Hub 上的模型，或模型仓库中的文件。[别名：ls]

在不带参数调用时，列出 Hub 上的模型。 在传入模型 ID 时，列出该模型仓库中的文件。

用法：

$ hf models list [OPTIONS] [REPO_ID]

参数：

• [REPO_ID]：模型 ID（例如 username/repo-name），用于列出该模型的文件。如果省略，则列出所有模型。

选项：

• --search TEXT：搜索查询。
• --author TEXT：按作者或组织进行筛选。
• --filter TEXT：按标签筛选（例如 ‘text-classification’）。可多次使用。
• --pipeline-tag TEXT：按流水线标签（标准任务）进行筛选，例如 ‘summarization’。
• --gated / --no-gated：按受限状态筛选。‘—gated’ 仅显示受限模型，‘—no-gated’ 仅显示非受限模型。
• --apps TEXT：按能够运行该模型的应用进行筛选，例如 ‘ollama’ 或 ‘vllm’。
• --num-parameters TEXT：按参数量筛选，例如 ‘min:6B,max:128B’。
• --inference-provider [baseten|cerebras|cohere|deepinfra|fal-ai|featherless-ai|fireworks-ai|groq|hf-inference|novita|nscale|openai|ovhcloud|publicai|replicate|scaleway|together|wavespeed|zai-org]：按提供该模型推理服务的提供商进行筛选，例如 ‘fireworks-ai’。
• --warm：仅列出当前至少由一个推理提供商提供的模型。
• --sort [created_at|downloads|last_modified|likes|trending_score]：对结果进行排序。
• --limit INTEGER：限制结果数量。 [默认值：30]
• --expand TEXT：要返回的逗号分隔的属性。使用时，仅返回列出的属性（以及 id）。示例：‘—expand=downloads,likes,tags’。有效值：author, baseModels, cardData, childrenModelCount, config, createdAt, disabled, downloads, downloadsAllTime, evalResults, gated, gguf, inference, inferenceProviderMapping, lastModified, library_name, likes, mask_token, model-index, pipeline_tag, private, resourceGroup, safetensors, sha, siblings, spaces, tags, transformersInfo, trendingScore, usedStorage, widgetData。
• -h, --human-readable：以人类可读的格式显示大小（仅适用于列出文件）。
• --tree：以树状格式列出文件（仅用于列出文件）。
• -R, --recursive：递归列出文件（仅用于列出文件）。
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf models ls —sort downloads —limit 10 $ hf models ls —search “llama” —author meta-llama $ hf models ls —pipeline-tag text-generation —warm $ hf models ls —num-parameters min:6B,max:128B —sort likes $ hf models ls —no-gated —author google $ hf models ls —apps llama.cpp —apps vllm $ hf models ls —inference-provider fireworks-ai —sort downloads $ hf models ls —warm —search llama $ hf models ls meta-llama/Llama-3.2-1B-Instruct $ hf models ls meta-llama/Llama-3.2-1B-Instruct -R $ hf models ls meta-llama/Llama-3.2-1B-Instruct —tree -h

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf papers

在 Hub 上与论文进行交互。

用法：

$ hf papers [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• info：获取 Hub 上某篇论文的信息。
• list：列出 Hub 上的每日论文。[别名：ls]
• read：以 Markdown 格式读取论文。
• search：在 Hub 上搜索论文。

hf papers info

获取 Hub 上某篇论文的信息。

用法：

$ hf papers info [OPTIONS] PAPER_ID

参数：

• PAPER_ID：arXiv 论文 ID（例如 ‘2502.08025’）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf papers info 2601.15621

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf papers list

在 Hub 上列出每日论文。[alias: ls]

用法：

$ hf papers list [OPTIONS]

选项：

• --date TEXT：ISO 格式（YYYY-MM-DD）的日期或 ‘today’。
• --week TEXT：用于筛选的 ISO 周，例如 ‘2025-W09’。
• --month TEXT：用于按 ISO 格式（YYYY-MM）筛选的月份，例如 ‘2025-02’。
• --submitter TEXT：按提交者的用户名进行筛选。
• --sort [publishedAt|trending]：对结果进行排序。
• --limit INTEGER：限制结果数量。 [默认值：50]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf papers ls $ hf papers ls —sort trending $ hf papers ls —date 2025-01-23 $ hf papers ls —week 2025-W09 $ hf papers ls —submitter akhaliq $ hf papers ls —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf papers read

以 Markdown 格式读取论文。

用法：

$ hf papers read [OPTIONS] PAPER_ID

参数：

• PAPER_ID：arXiv 论文 ID（例如 ‘2502.08025’）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf papers read 2601.15621

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf papers search

在 Hub 上搜索论文。

用法：

$ hf papers search [OPTIONS] QUERY

参数：

• QUERY：搜索查询字符串。 [必填]

选项：

• --limit INTEGER：限制结果数量。 [默认值：20]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf papers search “vision language” $ hf papers search “attention mechanism” —limit 10 $ hf papers search “diffusion” —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos

在 Hub 上管理仓库。

用法：

$ hf repos [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• branch：管理 Hub 上仓库的分支。
• cp：在本地路径、仓库和存储桶之间复制文件。
• create：在 Hub 上创建一个新的仓库。
• delete：从 Hub 中删除一个仓库。
• delete-files：从 Hub 上的仓库中删除文件。
• duplicate：在 Hub 上复制一个仓库（模型、数据集或 Space）。
• list：列出所有仓库（模型、数据集、空间、存储桶）及其存储信息。[别名：ls]
• move：将仓库从一个命名空间移动到另一个命名空间。
• settings：更新仓库的设置。
• tag：管理 Hub 上仓库的标签。

hf repos branch

在 Hub 上管理仓库的分支。

用法：

$ hf repos branch [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• create：在 Hub 上为仓库创建新分支。
• delete：从 Hub 上的仓库中删除一个分支。

hf repos branch create

在 Hub 上为仓库创建新分支。

用法：

$ hf repos branch create [OPTIONS] REPO_ID BRANCH

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• BRANCH：要创建的分支名称。 [必填]

选项：

• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --exist-ok / --no-exist-ok：如果设置为 True，则分支已存在时不抛出错误。 [默认值：no-exist-ok]
• --help：显示此消息并退出。

示例 $ hf repos branch create my-model dev $ hf repos branch create my-model dev —revision abc123

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos branch delete

从 Hub 上的仓库中删除一个分支。

用法：

$ hf repos branch delete [OPTIONS] REPO_ID BRANCH

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• BRANCH：要删除的分支名称。 [必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --help：显示此消息并退出。

示例 $ hf repos branch delete my-model dev

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos cp

在本地路径、仓库和存储桶之间复制文件。

处理上传（本地/stdin -> 仓库/存储桶）、下载（仓库/存储桶 -> 本地/stdout）以及远程到远程的复制（仓库/存储桶 -> 仓库/存储桶）。不支持存储桶到仓库以及本地到本地的复制。对于目录，请使用 hf upload/hf download（仓库）或 hf buckets sync（存储桶）。远程到远程的复制仅在相同的存储区域内有效（https://huggingface.co/docs/hub/storage-regions）。

用法：

$ hf repos cp [OPTIONS] SRC [DST]

参数：

• SRC：源：本地文件、hf:// URI（仓库或存储桶），或 - 表示标准输入。 [必填]
• [DST]：目标：本地路径、hf:// URI（仓库或存储桶），或 - 表示标准输出。

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf repos cp hf://username/my-model/config.json config.json $ hf repos cp hf://datasets/username/my-dataset/data.csv data/ $ hf repos cp hf://username/my-model/config.json - $ hf repos cp model.safetensors hf://username/my-model/model.safetensors $ hf repos cp config.json hf://username/my-model/logs/ $ hf repos cp - hf://username/my-model/config.json $ hf repos cp hf://username/source-model/config.json hf://username/dest-model/config.json $ hf repos cp hf://datasets/username/my-dataset/processed/ hf://datasets/username/dest-dataset/processed/ $ hf repos cp hf://username/my-model/logs/ hf://username/archive-model/logs/

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos create

在 Hub 上创建一个新仓库。

用法：

$ hf repos create [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --sdk, --space-sdk TEXT：Hugging Face Spaces SDK 类型。当 —type 设置为 ‘space’ 时必填。
• --template TEXT：从官方模板创建 Space。传入模板仓库 ID（例如 ‘SpacesExamples/jupyterlab’）或其短名称（例如 ‘JupyterLab’）。使用 hf spaces templates 列出可用模板。仅限 Spaces。
• --private / --no-private：如果 Hub 上不存在该仓库，是否创建私有仓库。如果仓库已存在，则忽略此选项。
• --public：是否将仓库设为公开。如果仓库已存在，则忽略此参数。
• --protected：是否将 Space 设为受保护状态（仅适用于 Spaces）。如果仓库已存在，则忽略此参数。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --exist-ok / --no-exist-ok：如果仓库已存在，则不引发错误。 [默认值：no-exist-ok]
• --resource-group-id TEXT：用于创建仓库的资源组。资源组仅适用于 Enterprise Hub 组织。
• --region [us|eu]：创建仓库所在的云区域。可以是 ‘us’ 或 ‘eu’。需要 Team 套餐或更高版本。
• --flavor [cpu-basic|cpu-upgrade|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：Space 硬件规格（例如 ‘cpu-basic’、‘t4-medium’、‘l4x4’）。仅适用于 Spaces。
• --sleep-time INTEGER：Space 进入休眠状态前的不活动秒数。使用 -1 可禁用此功能。仅适用于 Spaces。
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认为读写。例如 -v hf://org/m:/data 或 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro
• --help：显示此消息并退出。

示例 $ hf repos create my-model $ hf repos create my-dataset —repo-type dataset —private $ hf repos create my-space —type space —sdk gradio —flavor t4-medium —secrets HF_TOKEN -e THEME=dark —protected $ hf repos create my-jupyterlab —type space —template SpacesExamples/jupyterlab $ hf repos create my-space —type space —sdk gradio -v hf://org/my-model:/models -v hf://buckets/org/b:/data $ hf repos create my-model —region us

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos delete

从 Hub 中删除一个仓库。此操作不可逆。

用法：

$ hf repos delete [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --missing-ok / --no-missing-ok：如果设置为 True，则即使仓库不存在也不会引发错误。 [默认值：no-missing-ok]
• -y, --yes：自动对提示回答“是”。
• --help：显示此消息并退出。

示例 $ hf repos delete my-model

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos delete-files

从 Hub 上的仓库中删除文件。

用法：

$ hf repos delete-files [OPTIONS] REPO_ID PATTERNS...

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• PATTERNS...：用于匹配要删除的文件的 Glob 模式。基于 fnmatch，'*' 会递归匹配文件。 [必填]

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --commit-message TEXT：生成的提交的摘要 / 标题 / 第一行。
• --commit-description TEXT：生成的提交的描述。
• --create-pr / --no-create-pr：是否为这些更改创建新的 Pull Request。 [默认值：no-create-pr]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf repos delete-files my-model file.txt $ hf repos delete-files my-model “*.json” $ hf repos delete-files my-model folder/

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos duplicate

在 Hub 上复制一个仓库（模型、数据集或 Space）。

用法：

$ hf repos duplicate [OPTIONS] FROM_ID [TO_ID]

参数：

• FROM_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• [TO_ID]：目标仓库 ID（例如 myorg/my-copy）。默认值为您命名空间下具有相同仓库名称的仓库。

选项：

• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --private / --no-private：如果 Hub 上不存在该仓库，是否创建私有仓库。如果仓库已存在，则忽略此选项。
• --public：是否将仓库设为公开。如果仓库已存在，则忽略此参数。
• --protected：是否将 Space 设为受保护状态（仅适用于 Spaces）。如果仓库已存在，则忽略此参数。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --exist-ok / --no-exist-ok：如果仓库已存在，则不引发错误。 [默认值：no-exist-ok]
• --resource-group-id TEXT：用于创建新仓库的资源组。资源组仅适用于 Enterprise Hub 组织。
• --flavor [cpu-basic|cpu-upgrade|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：Space 硬件规格（例如 ‘cpu-basic’、‘t4-medium’、‘l4x4’）。仅适用于 Spaces。
• --sleep-time INTEGER：Space 进入休眠状态前的不活动秒数。使用 -1 可禁用此功能。仅适用于 Spaces。
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认为读写。例如 -v hf://org/m:/data 或 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro
• --help：显示此消息并退出。

示例 $ hf repos duplicate openai/gdpval —type dataset $ hf repos duplicate multimodalart/dreambooth-training my-dreambooth —type space —flavor l4x4 —secrets HF_TOKEN —private $ hf repos duplicate org/my-space my-space —type space -v hf://org/my-model:/models -v hf://buckets/org/b:/data

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos list

列出所有仓库（模型、数据集、空间、存储桶）及其存储信息。[别名：ls]

用法：

$ hf repos list [OPTIONS]

选项：

• --namespace TEXT：组织名称。如果未提供，则列出已认证用户的仓库。
• --type, --repo-type [model|dataset|space|bucket]：按仓库类型（model、dataset、space 或 bucket）进行筛选。
• --search TEXT：搜索查询。
• --limit INTEGER：限制结果数量。 [默认值：30]
• --explore：以交互式 3D 城市的形式探索你的仓库。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf repos ls $ hf repos ls —explore $ hf repos ls —namespace my-org —search bert

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos move

将一个仓库从一个命名空间移动到另一个命名空间。

用法：

$ hf repos move [OPTIONS] FROM_ID TO_ID

参数：

• FROM_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• TO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --help：显示此消息并退出。

示例 $ hf repos move old-namespace/my-model new-namespace/my-model

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos settings

更新仓库的设置。

用法：

$ hf repos settings [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --gated [auto|manual|false]：仓库的受控状态。
• --private / --no-private：如果 Hub 上不存在该仓库，是否创建私有仓库。如果仓库已存在，则忽略此选项。
• --public：是否将仓库设为公开。如果仓库已存在，则忽略此参数。
• --protected：是否将 Space 设为受保护状态（仅适用于 Spaces）。如果仓库已存在，则忽略此参数。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --help：显示此消息并退出。

示例 $ hf repos settings my-model —private $ hf repos settings my-model —gated auto $ hf repos settings my-space —repo-type space —protected

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos tag

管理 Hub 上仓库的标签。

用法：

$ hf repos tag [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• create：为仓库创建标签。
• delete：删除仓库的标签。
• list：列出仓库的标签。[别名：ls]

hf repos tag create

为仓库创建一个标签。

用法：

$ hf repos tag create [OPTIONS] REPO_ID TAG

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• TAG：要创建的标签名称。 [必填]

选项：

• -m, --message TEXT：要创建的标签的描述。
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --help：显示此消息并退出。

示例 $ hf repos tag create my-model v1.0 $ hf repos tag create my-model v1.0 -m “First release”

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos tag delete

删除仓库的标签。

用法：

$ hf repos tag delete [OPTIONS] REPO_ID TAG

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]
• TAG：要删除的标签名称。 [必填]

选项：

• -y, --yes：自动对提示回答“是”
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --help：显示此消息并退出。

示例 $ hf repos tag delete my-model v1.0

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf repos tag list

列出仓库的标签。[别名: ls]

用法：

$ hf repos tag list [OPTIONS] REPO_ID

参数：

• REPO_ID：仓库的 ID（例如 username/repo-name 或 spaces/username/repo-name）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --type, --repo-type [model|dataset|space|kernel]：仓库的类型（model、dataset、space 或 kernel）。[默认值：model]
• --help：显示此消息并退出。

示例 $ hf repos tag list my-model

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox

在 Hugging Face Jobs 上运行和管理实验沙盒。

用法：

$ hf sandbox [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• cp：在本地机器和沙箱（docker 风格）之间复制文件。
• create：创建一个沙箱：默认情况下是一个专用的虚拟机，或者使用 --pool 创建一个低成本的共享虚拟机。
• exec：在沙箱中运行命令，并流式输出结果。
• kill：终止一个沙箱、整个共享主机或所有进程（—all）。
• pool：预热主机虚拟机池，并为同一信任边界内的工作负载生成实验性共享沙箱。
• process：列出并停止在沙箱中运行的后台进程。
• spawn：在后台启动一个长时间运行的命令并返回其 pid（不等待）。

hf sandbox cp

在本地机器和沙箱（docker 风格）之间复制文件。

用法：

$ hf sandbox cp [OPTIONS] SRC DST

参数：

• SRC：源：本地路径或 <sandbox_id>:<path>。 [必填]
• DST：目标：本地路径或 <sandbox_id>:<path>。 [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox cp data.csv <sandbox_id>:/data/data.csv $ hf sandbox cp <sandbox_id>:/app/result.json result.json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox create

创建一个沙箱：默认情况下是一个专用虚拟机，或者使用 --pool 创建一个低成本的共享虚拟机。

Env 和 idle-timeout 在两种模式下均适用于沙箱。使用 --pool 时，镜像和 flavor 来自池，因此在此处传递它们是错误的；--secrets 同样会被拒绝，因为池化沙箱没有加密密钥通道（请使用 --env）。请先使用 hf sandbox pool create 定义一个池。

用法：

$ hf sandbox create [OPTIONS] [IMAGE]

参数：

• [IMAGE]：Docker 镜像（需要 /bin/sh）。

选项：

• --pool TEXT：在此池中生成一个低成本的共享沙箱（来自 hf sandbox pool create）。
• --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：硬件的规格。运行 ‘hf jobs hardware’ 以列出可用的规格。默认为 cpu-basic。
• --idle-timeout TEXT：在此时长内无活动后自动终止沙箱（例如 ‘10m’）。默认值为 10m。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• -l, --label TEXT：设置标签。例如 —label KEY=VALUE 或 —label LABEL
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• -v, --volume TEXT：挂载一个或多个卷。格式：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]。TYPE 为以下之一：models、datasets、spaces、buckets。如果省略 TYPE，则默认为 models。models、datasets 和 spaces 始终以只读方式挂载。buckets 默认为读写。例如 -v hf://org/m:/data 或 -v hf://datasets/org/ds:/data 或 -v hf://buckets/org/b:/mnt:ro
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --forward-hf-token：将您的 HF token 作为 HF_TOKEN 注入到沙箱中。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox create $ hf sandbox create ubuntu:24.04 $ hf sandbox create —flavor a10g-small $ hf sandbox create —label controller-run=run-42 $ hf sandbox create —pool pool-ab12cd34ef56 —env LOG_LEVEL=debug

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox exec

在沙箱中运行命令，并流式传输输出。退出时返回该命令的退出码。

要在后台启动长时间运行的命令而不是等待其完成，请使用 hf sandbox spawn。

用法：

$ hf sandbox exec [OPTIONS] SANDBOX_ID COMMAND...

参数：

• SANDBOX_ID：由 hf sandbox create 打印的沙箱 ID。 [必填]
• COMMAND...：要运行的命令。 [必填]

选项：

• -w, --workdir TEXT：工作目录。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --timeout FLOAT：在此秒数后终止命令。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox exec <sandbox_id> — python -c “print(42)” $ hf sandbox exec -w /app <sandbox_id> — pytest -x

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox kill

终止一个沙箱、整个共享主机或所有资源（—all）。

用法：

$ hf sandbox kill [OPTIONS] [SANDBOX_ID]

参数：

• [SANDBOX_ID]：要终止的沙箱或主机 ID。

选项：

• --all：终止命名空间中的所有沙箱和主机。
• -y, --yes：自动对提示回答“是”。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox kill <sandbox_id> $ hf sandbox kill <host_id> # kills a whole shared host (all its sandboxes) $ hf sandbox kill —all

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox pool

预热主机虚拟机池，并为同一信任边界内的工作负载生成实验性共享沙箱。

用法：

$ hf sandbox pool [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• create：预热资源池：立即启动一台主机虚拟机，并打上标签，以便之后通过其资源池 ID 找到它。
• delete：终止池中的所有主机虚拟机（因此也会终止其所有沙箱）。[别名：rm]
• ls：列出正在运行的沙箱池（按其宿主虚拟机分组）。[别名：list]

hf sandbox pool create

预热资源池：立即启动一台主机虚拟机，并为其打上标签，以便后续通过其资源池 ID 找到它。

用法：

$ hf sandbox pool create [OPTIONS] [IMAGE]

参数：

• [IMAGE]：用于主机的 Docker 镜像（需要 /bin/sh）。

选项：

• --flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：硬件的规格。运行 ‘hf jobs hardware’ 以列出可用的规格。默认为 cpu-basic。
• --per-host INTEGER RANGE：每个主机虚拟机中打包的沙箱数量（默认 50）。 [default: 50; x>=1]
• --max-hosts INTEGER RANGE：主机虚拟机的数量上限（可选）。 [x>=1]
• --idle-timeout TEXT：当主机在此时长内没有沙箱时将其关闭（例如 ‘10m’）。默认值为 10m。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox pool create $ hf sandbox pool create python:3.12 —flavor cpu-basic $ hf sandbox pool create —per-host 50 —idle-timeout 30m

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox pool delete

终止池中的每个主机虚拟机（因此也会终止其所有沙箱）。[别名：rm]

用法：

$ hf sandbox pool delete [OPTIONS] POOL_ID

参数：

• POOL_ID：要删除的池 ID。 [必填]

选项：

• -y, --yes：自动对提示回答“是”。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox pool delete <pool_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox pool ls

列出正在运行的沙箱池（按其宿主虚拟机分组）。[别名: list]

用法：

$ hf sandbox pool ls [OPTIONS]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox pool ls

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox process

列出并停止在沙箱中运行的后台进程。

用法：

$ hf sandbox process [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• kill：停止在沙箱中运行的后台进程。
• ls：列出在沙箱中运行的后台进程（通过 hf sandbox spawn 启动）。[别名：list]

hf sandbox process kill

停止在沙箱中运行的后台进程。

用法：

$ hf sandbox process kill [OPTIONS] SANDBOX_ID PID

参数：

• SANDBOX_ID：由 hf sandbox create 打印的沙箱 ID。 [必填]
• PID：由 hf sandbox process ls 打印的 pid。 [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox process kill <sandbox_id> <pid>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox process ls

列出在沙箱中运行的后台进程（通过 hf sandbox spawn 启动）。[别名：list]

用法：

$ hf sandbox process ls [OPTIONS] SANDBOX_ID

参数：

• SANDBOX_ID：由 hf sandbox create 打印的沙箱 ID。 [必填]

选项：

• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox process ls <sandbox_id>

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf sandbox spawn

在后台启动一个长时间运行的命令并返回其 pid（不要等待）。

使用 hf sandbox process ls 列出沙箱中的进程，并使用 hf sandbox process kill 停止其中一个进程。

用法：

$ hf sandbox spawn [OPTIONS] SANDBOX_ID COMMAND...

参数：

• SANDBOX_ID：由 hf sandbox create 打印的沙箱 ID。 [必填]
• COMMAND...：要在后台运行的命令。 [必填]

选项：

• -w, --workdir TEXT：工作目录。
• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --namespace TEXT：作业将运行的命名空间。默认值为当前用户的命名空间。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf sandbox spawn <sandbox_id> — python -m http.server 8000 $ hf sandbox spawn -w /app <sandbox_id> — uvicorn app:app

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf skills

管理 AI 助手的技能。

用法：

$ hf skills [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• add：为 AI 助手安装 Hugging Face 技能。
• list：列出 Hugging Face 市场中的可用技能。[别名：ls]
• preview：将生成的 hf-cli SKILL.md 打印到标准输出。
• update：更新已安装的 Hugging Face 市场技能。

hf skills add

为 AI 助手安装 Hugging Face 技能。

默认的 hf-cli 技能是根据已安装的 CLI 版本在本地生成的； 其他技能则从 Hugging Face 市场下载。 默认位置位于当前目录（.agents/skills）或用户级别（~/.agents/skills）。 除非使用了 --dest，否则该技能还会通过符号链接放入 Claude Code 的技能目录（.claude/skills 或 ~/.claude/skills， 如果设置了 CLAUDE_CONFIG_DIR 则会遵循该设置）。

用法：

$ hf skills add [OPTIONS] [NAME]

参数：

• [NAME]：市场技能名称。

选项：

• -g, --global：全局安装（用户级别），而不是安装在当前项目目录中。
• --dest PATH：安装到自定义目标位置（skills 目录的路径）。
• --force：覆盖目标位置中已存在的技能。
• --help：显示此消息并退出。

示例 $ hf skills add $ hf skills add huggingface-gradio —dest=~/my-skills $ hf skills add —global $ hf skills add huggingface-gradio —global

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf skills list

列出 Hugging Face 市场中的可用技能。[alias: ls]

用法：

$ hf skills list [OPTIONS]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf skills list $ hf skills list —format json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf skills 预览

将生成的 hf-cli SKILL.md 打印到标准输出。

用法：

$ hf skills preview [OPTIONS]

选项：

• --help：显示此消息并退出。

hf skills update

更新已安装的 Hugging Face 市场技能。

用法：

$ hf skills update [OPTIONS] [NAME]

参数：

• [NAME]：要更新的可选已安装技能名称。

选项：

• -g, --global：使用全局技能目录，而不是当前项目。
• --dest PATH：在自定义技能目录中更新技能。
• --help：显示此消息并退出。

示例 $ hf skills update $ hf skills update hf-cli $ hf skills update huggingface-gradio —dest=~/my-skills $ hf skills update -g

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces

与 Hub 上的 spaces 进行交互。

用法：

$ hf spaces [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• card：获取 Hub 上某个 Space 的 Space 卡片（README）。
• dev-mode：在 Space 上启用或禁用开发模式。
• hardware：列出 Spaces 可用的硬件选项。
• hot-reload：无需完整重建和重启，即可热重载 Space 中的任意 Python 文件。
• info：获取 Hub 上某个空间的信息。
• list：列出 Hub 上的空间，或空间仓库中的文件。[别名：ls]
• logs：获取 Space 的运行或构建日志。
• pause：暂停一个 Space。
• restart：重启 Space。
• search：使用语义搜索在 Hub 上搜索空间。
• secrets：管理 Hub 上某个 Space 的密钥。
• settings：更新 Space 的设置。
• ssh：通过 SSH 连接到 Space 的 Dev Mode 容器。
• templates：列出可用的 Space 模板。
• variables：管理 Hub 上某个 Space 的环境变量。
• volumes：管理 Hub 上 Space 的卷。
• wait：等待 Space 完成构建/启动。
• zero-gpu：在 Hub 上管理您的 ZeroGPU 使用情况。

hf spaces 卡片

获取 Hub 上某个 Space 的 Space 卡片（README）。

用法：

$ hf spaces card [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --metadata：仅输出卡片中的元数据。
• --text：仅输出文本正文（不包含元数据）。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces card mteb/leaderboard $ hf spaces card mteb/leaderboard —metadata $ hf spaces card mteb/leaderboard —metadata —format json $ hf spaces card mteb/leaderboard —text

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces dev-mode

在 Space 上启用或禁用开发模式。

Spaces 开发模式可简化应用的调试流程，并允许在不停止 Space 容器本身的情况下重启应用，从而加快 Spaces 的迭代速度。启用开发模式需要 PRO 或 Team & Enterprise 套餐。禁用它（--stop）始终被允许。

查看文档：https://huggingface.co/docs/hub/spaces-dev-mode

用法：

$ hf spaces dev-mode [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --stop / --no-stop：停止开发模式。 [默认值：no-stop]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces dev-mode my-user-name/deepsite

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces 硬件

列出 Spaces 可用的硬件选项。

用法：

$ hf spaces hardware [OPTIONS]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces hardware

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces 热重载

无需完整重建和重启，即可热重载 Space 中的任意 Python 文件。

⚠ 此功能为实验性功能 ⚠

仅适用于 Gradio SDK（6.1+） 除非指定了 —local-file/-f，否则将打开交互式编辑器。

此命令使用 https://github.com/breuleux/jurigged（基于 AST 的差异比较、原地函数更新等）来修补正在运行的 Python 进程，并与 Gradio 的原生热重载支持集成（这意味着 Gradio 演示对象的变化会反映在 UI 中）

该命令会创建一个远程提交。 如果您正在本地克隆仓库中工作，请在之后运行 git pull --autostash，以将该提交拉取回来并保持本地 git 状态同步。

用法：

$ hf spaces hot-reload [OPTIONS] SPACE_ID [FILENAME]

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]
• [FILENAME]：Space 仓库中 Python 文件的路径。如果指定了 —local-file 且仓库中的路径匹配，则可以省略。

选项：

• -f, --local-file PATH：本地文件的路径。如果未指定，则进入交互式编辑器模式
• --skip-checks / --no-skip-checks：跳过热重载兼容性检查。 [默认值：no-skip-checks]
• --skip-summary / --no-skip-summary：在触发热重载后跳过摘要显示 [默认值：no-skip-summary]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces hot-reload username/repo-name app.py # Open an interactive editor to the remote app.py file $ hf spaces hot-reload username/repo-name -f app.py # Take local version from ./app.py and patch app.py remotely $ hf spaces hot-reload username/repo-name app.py -f src/app.py # Take local version from ./src/app.py

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces info

获取 Hub 上某个空间的信息。

用法：

$ hf spaces info [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --expand TEXT：要返回的逗号分隔的属性。使用时，仅返回列出的属性（以及 id）。示例：‘—expand=likes,tags’。有效值：author, cardData, createdAt, datasets, disabled, lastModified, likes, models, private, region, resourceGroup, runtime, sdk, sha, siblings, subdomain, tags, trendingScore, usedStorage, visibility。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces info enzostvs/deepsite $ hf spaces info gradio/theme_builder —expand sdk,runtime,likes

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces list

列出 Hub 上的空间，或空间仓库中的文件。[别名：ls]

在不带参数调用时，列出 Hub 上的空间。 在传入空间 ID 时，列出该空间仓库中的文件。

用法：

$ hf spaces list [OPTIONS] [REPO_ID]

参数：

• [REPO_ID]：Space ID（例如 username/repo-name），用于列出其中的文件。如果省略，则列出所有 spaces。

选项：

• --search TEXT：搜索查询。
• --author TEXT：按作者或组织进行筛选。
• --filter TEXT：按标签筛选（例如 ‘text-classification’）。可多次使用。
• --sort [created_at|last_modified|likes|trending_score]：对结果进行排序。
• --limit INTEGER：限制结果数量。 [默认值：30]
• --expand TEXT：要返回的逗号分隔的属性。使用时，仅返回列出的属性（以及 id）。示例：‘—expand=likes,tags’。有效值：author, cardData, createdAt, datasets, disabled, lastModified, likes, models, private, region, resourceGroup, runtime, sdk, sha, siblings, subdomain, tags, trendingScore, usedStorage, visibility。
• -h, --human-readable：以人类可读的格式显示大小（仅适用于列出文件）。
• --tree：以树状格式列出文件（仅用于列出文件）。
• -R, --recursive：递归列出文件（仅用于列出文件）。
• --revision TEXT：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces ls —limit 10 $ hf spaces ls —search “chatbot” —author huggingface $ hf spaces ls victor/deepsite $ hf spaces ls victor/deepsite -R $ hf spaces ls victor/deepsite —tree -h

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces logs

获取 Space 的运行或构建日志。

默认情况下，打印当前可用的运行日志并退出（非阻塞，类似于 docker logs）。使用 —follow/-f 可流式传输日志，直到服务器关闭流。 使用 —build 可查看容器构建日志（当 Space 卡在 BUILD_ERROR 时很有用）。

用法：

$ hf spaces logs [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --build：获取容器的构建日志，而非运行日志。当 Space 卡在 BUILD_ERROR 状态时非常有用。
• -f, --follow：跟踪日志输出（持续流式传输，直到服务器关闭流）。如果不使用此标志，则仅打印当前可用的日志。
• -n, --tail INTEGER：显示日志末尾的行数。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces logs username/my-space $ hf spaces logs username/my-space —build $ hf spaces logs -f username/my-space $ hf spaces logs -n 50 username/my-space

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces pause

暂停一个 Space。

用法：

$ hf spaces pause [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces pause username/my-space

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces restart

重启一个 Space。

用法：

$ hf spaces restart [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --factory-reboot：不使用构建缓存，从头重建 Space。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces restart username/my-space $ hf spaces restart username/my-space —factory-reboot

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces search

在 Hub 上使用语义搜索查找搜索空间。

用法：

$ hf spaces search [OPTIONS] QUERY

参数：

• QUERY：搜索查询。[必填]

选项：

• --filter TEXT：按标签筛选（例如 ‘text-classification’）。可多次使用。
• --sdk TEXT：按 SDK 筛选（例如 gradio、docker、static）。
• --include-non-running / --no-include-non-running：在结果中包含未运行的空间。 [默认值：no-include-non-running]
• --description / --no-description：显示 AI 生成的描述。 [默认值：no-description]
• --limit INTEGER：限制结果数量。 [默认值：10]
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces search “generate image” $ hf spaces search “identify objects in pictures” —sdk gradio —limit 5 $ hf spaces search “remove background from photo” —description —json

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces secrets

管理 Hub 上某个 Space 的密钥。

用法：

$ hf spaces secrets [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• add：为 Space 添加或更新密钥。
• delete：从 Space 中删除一个密钥。
• list：列出 Space 的密钥。[别名：ls]

hf spaces secrets add

为 Space 添加或更新密钥。

用法：

$ hf spaces secrets add [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• -s, --secrets TEXT：设置机密环境变量。建议优先使用 --secrets SECRET 从您的环境中读取值（例如，使用 --secrets HF_TOKEN 来传递您的 Hugging Face 令牌）；--secrets SECRET=value 会将值写入您的 shell 历史记录中。
• --secrets-file TEXT：读取包含机密环境变量的文件。使用 - 从标准输入读取。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces secrets add username/my-space -s HF_TOKEN $ hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-… -s ANTHROPIC_API_KEY=sk-… $ hf spaces secrets add username/my-space —secrets-file .env.secrets

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces secrets delete

从 Space 中删除一个密钥。

用法：

$ hf spaces secrets delete [OPTIONS] SPACE_ID KEY

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]
• KEY：要删除的密钥的名称。 [必填]

选项：

• -y, --yes：自动对提示回答“是”。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces secrets delete username/my-space HF_TOKEN $ hf spaces secrets delete username/my-space HF_TOKEN —yes

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces secrets list

列出某个 Space 的密钥。密钥值仅可写入，不会返回。[别名: ls]

用法：

$ hf spaces secrets list [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces secrets ls username/my-space

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces 设置

更新 Space 的设置。

用法：

$ hf spaces settings [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --sleep-time INTEGER：Space 进入休眠状态前的空闲时间（以秒为单位）。使用 -1 表示永不休眠。仅在升级后的硬件上可用。
• --hardware [cpu-basic|cpu-upgrade|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|rtx-pro-6000|rtx-pro-6000x2|rtx-pro-6000x4|rtx-pro-6000x8]：Space 硬件规格（例如 ‘cpu-basic’、‘t4-medium’、‘l4x4’）。运行 ‘hf spaces hardware’ 以列出可用选项。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces settings username/my-space —sleep-time 300 $ hf spaces settings username/my-space —hardware t4-medium

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces ssh

通过 SSH 连接到 Space 的 Dev Mode 容器。

需要在 Space 上运行 Dev Mode，并且您的 SSH 公钥已注册在 https://huggingface.co/settings/keys。

参见：https://huggingface.co/docs/hub/spaces-dev-mode

用法：

$ hf spaces ssh [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• -i, --identity-file PATH：SSH 身份文件的路径（转发给 ssh -i）。
• --dry-run：打印 SSH 命令而不是执行它。
• --auto：如果尚未启用，则在不提示的情况下启用 Dev Mode。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces ssh username/my-space $ hf spaces ssh username/my-space —dry-run $ hf spaces ssh username/my-space -i ~/.ssh/id_ed25519 $ hf spaces ssh username/my-space —auto

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces 模板

列出可用的 Space 模板。

模板的 repo_id（或 name）可以传递给 hf repos create --template ...，以从该模板创建一个新的 Space。

用法：

$ hf spaces templates [OPTIONS]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces templates

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces 变量

管理 Hub 上某个 Space 的环境变量。

用法：

$ hf spaces variables [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• add：为 Space 添加或更新环境变量。
• delete：从 Space 中删除一个环境变量。
• list：列出 Space 的环境变量。[别名：ls]

hf spaces variables add

为 Space 添加或更新环境变量。

用法：

$ hf spaces variables add [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• -e, --env TEXT：设置环境变量。例如 —env ENV=value
• --env-file TEXT：读取包含环境变量的文件。使用 - 从标准输入读取。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces variables add username/my-space -e DEBUG=1 $ hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512 $ hf spaces variables add username/my-space —env-file .env

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces variables delete

从 Space 中移除环境变量。

用法：

$ hf spaces variables delete [OPTIONS] SPACE_ID KEY

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]
• KEY：要删除的变量名称。 [必填]

选项：

• -y, --yes：自动对提示回答“是”。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces variables delete username/my-space DEBUG $ hf spaces variables delete username/my-space DEBUG —yes

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces variables list

列出 Space 的环境变量。[alias: ls]

用法：

$ hf spaces variables list [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。

示例 $ hf spaces variables ls username/my-space

了解更多 使用 hf <command> --help 查看有关命令的更多信息。 在 https://huggingface.co/docs/huggingface_hub/en/guides/cli 阅读文档

hf spaces volumes

管理 Hub 上 Space 的卷。

用法：

$ hf spaces volumes [OPTIONS] COMMAND [ARGS]...

选项：

• --help：显示此消息并退出。

命令：

• delete：从 Space 中删除所有卷。
• list：列出在 Space 中挂载的卷。[别名：ls]
• set：为 Space 设置（替换）卷。

hf spaces volumes delete

从 Space 中移除所有卷。

用法：

$ hf spaces volumes delete [OPTIONS] SPACE_ID

参数：

• SPACE_ID：空间 ID（例如 username/repo-name）。[必填]

选项：

• -y, --yes：自动对提示回答“是”。
• --token TEXT：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
• --help：显示此消息并退出。