# 警告
# 此文件完全由 `hf` CLI 实现生成。
# 若要重新生成代码，请运行 `make style` 或 `python ./utils/generate_cli_reference.py --update`。
# 警告
-->

# `hf`

Hugging Face Hub CLI

**用法**：

```console
$ 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`

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

**用法**：

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

**选项**：

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

**命令**：

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

### `hf auth list`

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

**用法**：

```console
$ 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 的令牌。

**用法**：

```console
$ 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`

从特定令牌注销。

**用法**：

```console
$ 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`

在访问令牌之间切换。

**用法**：

```console
$ 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`

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

**用法**：

```console
$ 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 账户。

**用法**：

```console
$ 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`

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

**用法**：

```console
$ 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）。

**用法**：

```console
$ 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`

创建一个新的存储桶。

**用法**：

```console
$ 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` 来删除单个文件。

**用法**：

```console
$ 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`

获取存储桶的信息。

**用法**：

```console
$ 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）时调用，列出存储桶中的文件。

**用法**：

```console
$ 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`

Move 将存储桶重命名为新的名称或命名空间。

**用法**：

```console
$ 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`。

**用法**：

```console
$ 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 settings`

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

**用法**：

```console
$ 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`

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

**用法**：

```console
$ 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`

管理本地缓存目录。

**用法**：

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

**选项**：

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

**命令**：

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

### `hf cache list`

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

**用法**：

```console
$ 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`

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

**用法**：

```console
$ 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`

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

**用法**：

```console
$ 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 $ 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`

**用法**：

```console
$ 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 collections`

在 Hub 上与集合进行交互。

**用法**：

```console
$ 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`

向集合中添加一个项目。

**用法**：

```console
$ 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 上创建一个新的集合。

**用法**：

```console
$ 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 中删除一个集合。

**用法**：

```console
$ 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`

从集合中删除一个项目。

**用法**：

```console
$ 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 上某个集合的信息。

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 上更新集合的元数据。

**用法**：

```console
$ 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`

更新集合中的某个项目。

**用法**：

```console
$ 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）。

**用法**：

```console
$ 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/  # 仅复制内容

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

## `hf datasets`

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

**用法**：

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

**选项**：

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

**命令**：

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

### `hf datasets card`

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

**用法**：

```console
$ 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 上数据集的信息。

**用法**：

```console
$ 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 leaderboard`

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

**用法**：

```console
$ 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 时，列出该数据集仓库中的文件。

**用法**：

```console
$ 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。

**用法**：

```console
$ 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 查询。

**用法**：

```console
$ 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 discussions`

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

**用法**：

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

**选项**：

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

**命令**：

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

### `hf discussions close`

关闭讨论或拉取请求。

**用法**：

```console
$ 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 comment`

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

**用法**：

```console
$ 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'。正文中的 '![alt](FILE)' 引用将被替换为上传的文件，其他文件将被追加。可多次使用。
* `--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`

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

**用法**：

```console
$ 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'。正文中的 '![alt](FILE)' 引用将被替换为上传的文件，其他文件将被追加。可多次使用。
* `--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。

**用法**：

```console
$ 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 edit`

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

**用法**：

```console
$ 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'。正文中的 '![alt](FILE)' 引用将被替换为上传的文件，其他文件将被追加。可多次使用。
* `--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: ![result](./after.png)" --attach ./after.png

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

### `hf discussions info`

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

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 merge`

合并拉取请求。

**用法**：

```console
$ 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 rename`

重命名讨论或拉取请求。

**用法**：

```console
$ 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 reopen`

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

**用法**：

```console
$ 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 下载文件。

**用法**：

```console
$ 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。

**用法**：

```console
$ 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 catalog`

与 Inference Endpoints 目录进行交互。

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf endpoints catalog deploy`

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

Catalog 模型通过配方进行部署：一种已针对该模型测试过的硬件与引擎组合。传入 --repo 以部署模型的默认配方，可选地通过 --accelerator 和 --gguf-file 进一步限定，或者传入 --recipe 以部署由 `hf endpoints catalog ls` 列出的某个确切配方。

**用法**：

```console
$ 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>` 部署其中一个。

**用法**：

```console
$ 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`

永久删除推理端点。

**用法**：

```console
$ 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` 组合。

**用法**：

```console
$ 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`

获取现有端点的信息。

**用法**：

```console
$ 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 hardware`

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

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

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

**用法**：

```console
$ 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]

**用法**：

```console
$ 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>` 部署其中一个。

**用法**：

```console
$ 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`

暂停推理端点。

**用法**：

```console
$ 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`

恢复推理端点。

**用法**：

```console
$ 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`

将推理端点缩容至零。

**用法**：

```console
$ 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`

更新现有端点。

**用法**：

```console
$ 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`：附加到容器入口点的参数，以引号字符串形式提供并按 token 拆分（例如 "--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`

打印有关环境的信息。

**用法**：

```console
$ hf env [OPTIONS]
```

**选项**：

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

## `hf extensions`

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

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

**用法**：

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

**选项**：

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

**命令**：

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

### `hf extensions exec`

执行已安装的扩展。

**用法**：

```console
$ 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 包。请仅从您信任的来源进行安装。

**用法**：

```console
$ 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]

**用法**：

```console
$ hf extensions list [OPTIONS]
```

**选项**：

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

示例 $ hf extensions list

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

### `hf extensions remove`

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

**用法**：

```console
$ 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' 主题标签）。

**用法**：

```console
$ hf extensions search [OPTIONS]
```

**选项**：

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

示例 $ hf extensions search

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

### `hf extensions update`

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

**用法**：

```console
$ 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。

**用法**：

```console
$ 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`

取消任务

**用法**：

```console
$ 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

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

### `hf jobs expose`

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

**用法**：

```console
$ 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  8000 $ hf jobs expose  8000 --public 9000 $ hf jobs expose  --clear

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

### `hf jobs hardware`

列出作业可用的硬件选项

**用法**：

```console
$ hf jobs hardware [OPTIONS]
```

**选项**：

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

示例 $ hf jobs hardware

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

### `hf jobs inspect`

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

**用法**：

```console
$ 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

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

### `hf jobs labels`

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

**用法**：

```console
$ 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  --name training-v2 $ hf jobs labels  --label env=prod --label team=ml $ hf jobs labels  --clear

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

### `hf jobs list | ls | ps`

列出任务。

使用 `--status` 按状态进行筛选（可能的值参见 [JobStage](/docs/huggingface_hub/v2.4.0/zh/package_reference/jobs#huggingface_hub.JobStage)），使用 `--label` 按 `key=value` 标签进行筛选。Job 必须匹配所有筛选条件才会被列出。

**用法**：

```console
$ 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>` 以检查最终状态。

**用法**：

```console
$ 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 $ hf jobs logs -f $ hf jobs logs --tail 20 $ hf jobs logs -f --tail 100

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

### `hf jobs rerun`

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

**用法**：

```console
$ 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 $ hf jobs rerun --detach

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

### `hf jobs run`

运行任务。

**用法**：

```console
$ 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）。

**用法**：

```console
$ 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。

**用法**：

```console
$ 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

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

#### `hf jobs scheduled inspect`

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

**用法**：

```console
$ 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

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

#### `hf jobs scheduled labels`

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

**用法**：

```console
$ 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  --name daily-script $ hf jobs scheduled labels  --label env=prod --label team=ml $ hf jobs scheduled labels  --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` 标签进行筛选。要列出的计划任务必须匹配所有筛选条件。

**用法**：

```console
$ 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）的运行时间。

**用法**：

```console
$ 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  "0 9 * * 1"

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

#### `hf jobs scheduled resume`

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

**用法**：

```console
$ 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

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

#### `hf jobs scheduled run`

调度任务。

**用法**：

```console
$ 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`

Suspend （暂停）一个已调度的 Job。

**用法**：

```console
$ 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

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

#### `hf jobs scheduled trigger`

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

**用法**：

```console
$ 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

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

#### `hf jobs scheduled uv`

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

**用法**：

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

**选项**：

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

**命令**：

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

##### `hf jobs scheduled uv run`

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

**用法**：

```console
$ 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 注册。

**用法**：

```console
$ 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 $ hf jobs ssh  --dry-run $ hf jobs ssh  -i ~/.ssh/id_ed25519

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

### `hf jobs stats`

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

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

**用法**：

```console
$ 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 $ hf jobs stats -f

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

### `hf jobs uv`

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

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf jobs uv run`

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

**用法**：

```console
$ 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 必须属于同一个命名空间。

**用法**：

```console
$ 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 $ hf jobs wait $ 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 使用自定义的多部分传输代理，从而支持将大文件分块高效上传。

**用法**：

```console
$ hf lfs-enable-largefiles [OPTIONS] PATH
```

**参数**：

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

**选项**：

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

## `hf lfs-multipart-upload`

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

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

**用法**：

```console
$ hf lfs-multipart-upload [OPTIONS]
```

**选项**：

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

## `hf models`

与 Hub 上的模型进行交互。

**用法**：

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

**选项**：

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

**命令**：

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

### `hf models card`

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

**用法**：

```console
$ 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 上某个模型的信息。

**用法**：

```console
$ 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 时，列出该模型仓库中的文件。

**用法**：

```console
$ 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 状态进行筛选。'--gated' 仅显示 gated 模型，'--no-gated' 仅显示非 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 上与论文进行交互。

**用法**：

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

**选项**：

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

**命令**：

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

### `hf papers info`

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

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 格式读取论文。

**用法**：

```console
$ 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 上搜索论文。

**用法**：

```console
$ 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 上管理仓库。

**用法**：

```console
$ 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 上管理仓库的分支。

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf repos branch create`

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

**用法**：

```console
$ 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 上的仓库中删除一个分支。

**用法**：

```console
$ 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）。

**用法**：

```console
$ 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 上创建一个新仓库。

**用法**：

```console
$ 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 中删除一个仓库。此操作不可逆。

**用法**：

```console
$ 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 上的仓库中删除文件。

**用法**：

```console
$ 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）。

**用法**：

```console
$ 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]

**用法**：

```console
$ 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`

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

**用法**：

```console
$ 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`

更新仓库的设置。

**用法**：

```console
$ 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 上仓库的标签。

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf repos tag create`

为仓库创建一个标签。

**用法**：

```console
$ 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`

删除仓库的标签。

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 上运行和管理实验沙盒。

**用法**：

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

**选项**：

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

**命令**：

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

### `hf sandbox cp`

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

**用法**：

```console
$ hf sandbox cp [OPTIONS] SRC DST
```

**参数**：

* `SRC`：源：本地路径或 :。 [必填]
* `DST`：目标：本地路径或 :。 [必填]

**选项**：

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

示例 $ hf sandbox cp data.csv :/data/data.csv $ hf sandbox cp :/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` 定义一个池。

**用法**：

```console
$ 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`。

**用法**：

```console
$ 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  -- python -c "print(42)" $ hf sandbox exec -w /app  -- pytest -x

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

### `hf sandbox kill`

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

**用法**：

```console
$ 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 $ hf sandbox kill    # 终止整个共享主机（其所有沙箱） $ hf sandbox kill --all

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

### `hf sandbox pool`

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

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf sandbox pool create`

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

**用法**：

```console
$ 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]

**用法**：

```console
$ 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

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

#### `hf sandbox pool ls`

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

**用法**：

```console
$ 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`

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

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf sandbox process kill`

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

**用法**：

```console
$ 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

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

#### `hf sandbox process ls`

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

**用法**：

```console
$ 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

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

### `hf sandbox spawn`

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

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

**用法**：

```console
$ 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  -- python -m http.server 8000 $ hf sandbox spawn -w /app  -- uvicorn app:app

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

## `hf skills`

管理 AI 助手的技能。

**用法**：

```console
$ 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` 则遵循该设置）。

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 preview`

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

**用法**：

```console
$ hf skills preview [OPTIONS]
```

**选项**：

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

### `hf skills update`

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

**用法**：

```console
$ 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 进行交互。

**用法**：

```console
$ 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 card`

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

**用法**：

```console
$ 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

**用法**：

```console
$ 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 hardware`

列出 Spaces 可用的硬件选项。

**用法**：

```console
$ 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 hot-reload`

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

⚠ 此功能为实验性功能 ⚠

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

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

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

**用法**：

```console
$ 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     # 打开交互式编辑器以编辑远程 app.py 文件 $ hf spaces hot-reload username/repo-name -f app.py  # 从 ./app.py 获取本地版本并远程修补 app.py $ hf spaces hot-reload username/repo-name app.py -f src/app.py # 从 ./src/app.py 获取本地版本

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

### `hf spaces info`

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

**用法**：

```console
$ 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。
* `--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 时，列出该空间仓库中的文件。

**用法**：

```console
$ 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。
* `-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 时很有用）。

**用法**：

```console
$ 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。

**用法**：

```console
$ 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。

**用法**：

```console
$ 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 上使用语义搜索查找搜索空间。

**用法**：

```console
$ 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 的密钥。

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf spaces secrets add`

为 Space 添加或更新密钥。

**用法**：

```console
$ 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 中删除一个密钥。

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 settings`

更新 Space 的设置。

**用法**：

```console
$ 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

**用法**：

```console
$ 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 templates`

列出可用的 Space 模板。

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

**用法**：

```console
$ 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 variables`

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

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf spaces variables add`

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

**用法**：

```console
$ 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 中移除环境变量。

**用法**：

```console
$ 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]

**用法**：

```console
$ 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 的卷。

**用法**：

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

**选项**：

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

**命令**：

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

#### `hf spaces volumes delete`

从 Space 中移除所有卷。

**用法**：

```console
$ hf spaces volumes delete [OPTIONS] SPACE_ID
```

**参数**：

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

**选项**：

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

示例 $ hf spaces volumes delete username/my-space $ hf spaces volumes delete username/my-space --yes

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

#### `hf spaces volumes list`

列出在 Space 中挂载的卷。[alias: ls]

**用法**：

```console
$ hf spaces volumes list [OPTIONS] SPACE_ID
```

**参数**：

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

**选项**：

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

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

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

#### `hf spaces volumes set`

Set （替换）某个 Space 的 volumes。

**用法**：

```console
$ hf spaces volumes set [OPTIONS] SPACE_ID
```

**参数**：

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

**选项**：

* `-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
* `--token TEXT`：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
* `--help`：显示此消息并退出。

示例 $ hf spaces volumes set username/my-space -v hf://models/username/my-model:/models $ hf spaces volumes set username/my-space -v hf://buckets/username/my-bucket:/data -v hf://datasets/username/my-dataset:/datasets:ro

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

### `hf spaces wait`

等待 Space 完成构建/启动。

阻塞执行，直到 Space 离开中间阶段（BUILDING、APP_STARTING 等）并进入稳定阶段。如果 Space 处于 RUNNING 状态，则以退出码 0 退出；否则以非零退出码退出（例如 BUILD_ERROR、RUNTIME_ERROR）。

**用法**：

```console
$ hf spaces wait [OPTIONS] SPACE_ID
```

**参数**：

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

**选项**：

* `--timeout TEXT`：最大等待时间：int，单位为 s（秒，默认）、m（分钟）、h（小时）或 d（天）。
* `--token TEXT`：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
* `--help`：显示此消息并退出。

示例 $ hf spaces wait username/my-space $ hf spaces wait username/my-space --timeout 5m

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

### `hf spaces zero-gpu`

在 Hub 上管理您的 ZeroGPU 使用情况。

**用法**：

```console
$ hf spaces zero-gpu [OPTIONS] COMMAND [ARGS]...
```

**选项**：

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

**命令**：

* `quota`：显示您的 ZeroGPU 配额（剩余 GPU 时间和重置日期）。

#### `hf spaces zero-gpu quota`

显示您的 ZeroGPU 配额（剩余 GPU 时间和重置日期）。

数值以 GPU 秒为单位。使用 `--quiet` 时，仅打印剩余的 GPU 秒数。

**用法**：

```console
$ hf spaces zero-gpu quota [OPTIONS]
```

**选项**：

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

示例 $ hf spaces zero-gpu quota $ hf spaces zero-gpu quota --format json

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

## `hf sync`

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

**用法**：

```console
$ hf 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 update`

将 `hf` CLI 更新到最新版本。

**用法**：

```console
$ hf update [OPTIONS]
```

**选项**：

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

## `hf upload`

将文件或文件夹上传到 Hub。

包含大量文件的文件夹会被拆分为多个提交。如果文件夹上传中断，请重新运行相同的命令以继续上传。

**用法**：

```console
$ hf upload [OPTIONS] REPO_ID [LOCAL_PATH] [PATH_IN_REPO]
```

**参数**：

* `REPO_ID`：仓库的 ID（例如 `username/repo-name` 或 `spaces/username/repo-name`）。[必填]
* `[LOCAL_PATH]`：要上传的文件或文件夹的本地路径。支持通配符模式。默认值为当前目录。
* `[PATH_IN_REPO]`：文件或文件夹在仓库中的路径。默认值为文件或文件夹的相对路径。

**选项**：

* `--type, --repo-type [model|dataset|space|kernel]`：仓库的类型（model、dataset、space 或 kernel）。[默认值：(model)]
* `--revision TEXT`：Git 修订版本 ID，可以是分支名称、标签或提交哈希值。
* `--private / --no-private`：如果 Hub 上不存在该仓库，是否创建私有仓库。如果仓库已存在，则忽略此选项。
* `--include TEXT`：用于匹配要上传的文件的 Glob 模式。
* `--exclude TEXT`：用于从要上传的文件中排除的 Glob 模式。
* `--delete TEXT`：在提交时从仓库中删除的文件所使用的全局匹配模式。
* `--commit-message TEXT`：生成的提交的摘要 / 标题 / 第一行。
* `--commit-description TEXT`：生成的提交的描述。
* `--create-pr / --no-create-pr`：是否将内容作为新的 Pull Request 上传。 [默认值：no-create-pr]
* `--every FLOAT`：如果设置，将安排一个后台任务，每隔 `every` 分钟创建一次提交。
* `--token TEXT`：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
* `--help`：显示此消息并退出。

示例 $ hf upload my-cool-model . . $ hf upload Wauplin/my-cool-model ./models/model.safetensors $ hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset $ hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%" $ hf upload bigcode/the-stack . . --repo-type dataset --create-pr

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

## `hf version`

打印 hf 版本信息。

**用法**：

```console
$ hf version [OPTIONS]
```

**选项**：

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

## `hf webhooks`

在 Hub 上管理 Webhook。

**用法**：

```console
$ hf webhooks [OPTIONS] COMMAND [ARGS]...
```

**选项**：

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

**命令**：

* `create`：创建新的 webhook。
* `delete`：永久删除 webhook。
* `disable`：禁用已激活的 webhook。
* `enable`：启用已禁用的 webhook。
* `info`：显示单个 webhook 的完整详细信息。
* `list`：列出当前用户的所有 Webhook。[别名：ls]
* `update`：更新现有的 webhook。

### `hf webhooks create`

创建新的 webhook。

请提供 --url（用于 ping 远程服务器）或 --job-id（用于触发 Job），但两者不可同时提供。源 Job 的 secrets 不会复制到 webhook 中：请再次通过 --secrets / --secrets-file 传入。

**用法**：

```console
$ hf webhooks create [OPTIONS]
```

**选项**：

* `--watch TEXT`：要监控的项目，格式为 'type:name'（例如 'model:bert-base-uncased'）。可重复使用。 [必填]
* `--url TEXT`：用于发送 webhook 负载的 URL。与 --job-id 互斥。
* `--job-id TEXT`：要触发的 Job 的 ID（来自 job.id），用于替代 ping 一个 URL。与 --url 互斥。
* `--domain [repo|discussion]`：要监控的域：'repo' 或 'discussion'。可重复使用。默认监控所有域。
* `--secret TEXT`：用于对 webhook 负载进行签名的可选密钥。
* `-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 webhooks create --url https://example.com/hook --watch model:bert-base-uncased $ hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repo $ hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-c $ hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKEN

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

### `hf webhooks delete`

永久删除 webhook。

**用法**：

```console
$ hf webhooks delete [OPTIONS] WEBHOOK_ID
```

**参数**：

* `WEBHOOK_ID`：要删除的 webhook 的 ID。 [必填]

**选项**：

* `-y, --yes`：跳过确认提示。
* `--token TEXT`：从 https://huggingface.co/settings/tokens 生成的用户访问令牌。
* `--help`：显示此消息并退出。

示例 $ hf webhooks delete abc123 $ hf webhooks delete abc123 --yes

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

### `hf webhooks disable`

禁用一个处于活动状态的 webhook。

**用法**：

```console
$ hf webhooks disable [OPTIONS] WEBHOOK_ID
```

**参数**：

* `WEBHOOK_ID`：要禁用的 webhook 的 ID。 [必填]

**选项**：

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

示例 $ hf webhooks disable abc123

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

### `hf webhooks enable`

启用已禁用的 webhook。

**用法**：

```console
$ hf webhooks enable [OPTIONS] WEBHOOK_ID
```

**参数**：

* `WEBHOOK_ID`：要启用的 webhook 的 ID。 [必填]

**选项**：

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

示例 $ hf webhooks enable abc123

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

### `hf webhooks info`

显示单个 webhook 的完整详细信息。

**用法**：

```console
$ hf webhooks info [OPTIONS] WEBHOOK_ID
```

**参数**：

* `WEBHOOK_ID`：Webhook 的 ID。[必填]

**选项**：

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

示例 $ hf webhooks info abc123

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

### `hf webhooks list`

列出当前用户的所有 webhook。[别名: ls]

**用法**：

```console
$ hf webhooks list [OPTIONS]
```

**选项**：

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

示例 $ hf webhooks ls $ hf webhooks ls --format json $ hf webhooks ls --format quiet

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

### `hf webhooks update`

更新现有的 webhook。仅更改提供的选项。

通过 --secrets 传递的作业密钥会替换同名的已存储值；其他值则保持不变。

**用法**：

```console
$ hf webhooks update [OPTIONS] WEBHOOK_ID
```

**参数**：

* `WEBHOOK_ID`：要更新的 webhook 的 ID。 [必填]

**选项**：

* `--url TEXT`：用于发送 webhook 负载的新 URL。
* `--job-id TEXT`：要触发的源 Job 的 ID（可以是当前 Job）。使用 --secrets / --secrets-file 时必填。
* `--watch TEXT`：要监控的新项目列表，格式为 'type:name'。可重复使用。将替换现有的整个监控列表。
* `--domain [repo|discussion]`：要关注的新域名列表：'repo' 或 'discussion'。可重复使用。
* `--secret TEXT`：用于对 webhook 负载进行签名的新密钥。
* `-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 webhooks update abc123 --url https://new-url.com/hook $ hf webhooks update abc123 --watch model:gpt2 --domain repo $ hf webhooks update abc123 --secret newsecret $ hf webhooks update abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKEN

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