前言¶
在 Hugging Face 上拉模型、推 checkpoint、管缓存或部署 Inference Endpoint，日常多半靠 hf（原 huggingface-cli）或 Python huggingface_hub。把同样的事交给 coding Agent 时，常见问题不是「不会写脚本」，而是子命令、参数和认证路径被记错——例如仍用已弃用的 huggingface-cli，或把 whoami 当成顶层命令。
下面介绍 Hugging Face 官方仓库里的 hf-cli Skill：把 Hub CLI 的用法写进 Agent 可遵循的说明，覆盖下载、上传、缓存、认证以及 buckets、jobs、endpoints 等扩展能力，减少幻觉命令。
这是什么¶
hf-cli 是 Hugging Face skills 仓库 中的一个 Agent Skill，面向终端工具 hf（Hugging Face Hub CLI）。资料写明：hf 用于在 Hub 上下载、上传和管理模型、数据集、Spaces、buckets、仓库、论文、jobs 等；并替代已弃用的 huggingface-cli。
Skill 的触发范围较宽：用户提到 hf、huggingface、Hugging Face、huggingface-cli、或要做 Hub / ML 生态相关操作（含训练 checkpoint、数据管道、云存储同步）时，应优先启用；即用户未明确要求「给一条 CLI」也适用。说明内容由 huggingface_hub v2.2.0 生成，可用 hf skills add --force 重新生成。
核心功能¶
Skill 内嵌的是 hf 命令体系，而非单独的可执行程序。按资料可核对的能力包括：
- 仓库与文件：
hf download、hf upload、hf cp；支持--type（model / dataset / space / kernel）、revision、include / exclude、本地目录与缓存目录等。 - 认证：统一在
hf auth下，例如hf auth login、hf auth whoami、hf auth list、hf auth switch、hf auth logout。 - 本地缓存：
hf cache list、hf cache prune、hf cache rm、hf cache verify。 - Buckets 与同步：
hf buckets子命令（create、list、cp、sync 等）及顶层hf sync（本地目录与 bucket 同步）。 - Hub 资源浏览与管理：
hf datasets、hf collections等（Skill 文档中含 datasets card / info / leaderboard / list 等；资料在 datasets 段有截断，其余子命令以 Skill 内 Commands 列表为准）。 - 环境与维护：
hf env、hf version、hf update。 - 输出格式：多数命令支持
--format [auto|human|agent|json|quiet]，便于 Agent 解析结果。
officialskills.sh 上的说明 补充概括：hf 在单一二进制中覆盖 Hub 生命周期的一部分场景——下载、上传、缓存、Inference Endpoints、jobs、webhooks 等，减少在网页、Python 与多套工具之间切换。具体子命令仍以 GitHub Skill 文档为准。
安装与启用¶
分两层：本机安装 hf CLI，以及在 Agent 环境中安装 Skill。
安装 hf CLI¶
官方安装命令：
curl -LsSf https://hf.co/cli/install.sh | bash -s
安装后可用 hf --help 查看子命令；认证相关均在 hf auth 下。
将 hf-cli Skill 加入 Agent¶
officialskills.sh 给出的方式为：
npx skills add https://github.com/huggingface/skills --skill hf-cli
也可在对话中提供 Skill 目录链接，由 coding assistant 按项目约定安装：
https://github.com/huggingface/skills/tree/main/skills/hf-cli
资料未区分 Cursor、Codex CLI、Claude Code 的安装差异时，以上述 npx skills add 与仓库路径为准。
典型用法¶
以下示例均来自 Skill 文档中的命令定义，可按需替换 REPO_ID、路径与 token。
确认环境与登录身份
hf env
hf auth whoami
首次或换账号时，在浏览器或 token 登录（token 可在 huggingface.co/settings/tokens 创建）：
hf auth login
下载指定模型到本地目录
hf download REPO_ID --type model --local-dir ./my-model --revision main
需要只看计划、不真正下载时，可使用文档中的 --dry-run；大仓库可配合 --max-workers 等参数（见 hf download --help）。
上传文件夹到 Hub
hf upload REPO_ID ./output-folder --type model --commit-message "Add checkpoint"
私有仓库可加 --private；若希望通过 PR 合入，文档提供 --create-pr。
查看并清理缓存
hf cache list --sort size:desc
hf cache prune --dry-run
本地训练目录与 bucket 同步
hf buckets sync --dry-run
hf sync --dry-run
实际执行前建议先用 --dry-run 核对将变更的文件；hf sync 与 hf buckets sync 在文档中均支持 include / exclude、delete 等选项。
更新 CLI 本身
hf update
适用场景与注意¶
适合谁
- 经常在 Hub 上下载固定 revision、上传大体积权重或数据集的 ML 工程师。
- 希望 Agent 代为写命令、查参数，且要求与当前
hf行为一致（含弃用huggingface-cli后的迁移）的团队。 - 需要顺带处理 buckets 同步、缓存校验、collections / datasets 查询等 Hub 周边操作的场景。
注意
- Skill 描述强调：凡 Hub 生态相关任务应启用本 Skill，避免 Agent 编造不存在的子命令或旧版
huggingface-cli接口。 - 认证与 token 管理涉及安全：
hf auth token会把当前 token 打到 stdout，在共享日志或 Agent transcript 中需自行脱敏。 - 文档由
huggingface_hub版本生成；Hub 新增子命令后，可运行hf skills add --force与本地hf update保持说明与二进制一致。 - 已抓取资料对
hf datasets之后的长命令列表有截断，遇到未在文中列出的能力时，应以hf <子命令> --help及 官方 Skill 目录 中的完整 Commands 段为准。
结尾¶
hf-cli 的价值在于：把 Hugging Face 官方 Hub CLI（hf）的边界写进 Agent 工作流——下载、上传、缓存、认证及 buckets 等操作有据可查，并明确替代已弃用的 huggingface-cli。安装 CLI 与 Skill 后，让 Agent 在涉及 hf 或 Hugging Face Hub 时默认走这套说明即可。
- Skill 目录：https://github.com/huggingface/skills/tree/main/skills/hf-cli
- CLI 安装：https://hf.co/cli/install.sh（经
curl管道执行，见上文命令）
