前言¶

在 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 命令體系，而非單獨的可執行程序。按資料可覈對的能力包括：

1. 倉庫與文件：hf download、hf upload、hf cp；支持 --type（model / dataset / space / kernel）、revision、include / exclude、本地目錄與緩存目錄等。
2. 認證：統一在 hf auth 下，例如 hf auth login、hf auth whoami、hf auth list、hf auth switch、hf auth logout。
3. 本地緩存：hf cache list、hf cache prune、hf cache rm、hf cache verify。
4. Buckets 與同步：hf buckets 子命令（create、list、cp、sync 等）及頂層 hf sync（本地目錄與 bucket 同步）。
5. Hub 資源瀏覽與管理：hf datasets、hf collections 等（Skill 文檔中含 datasets card / info / leaderboard / list 等；資料在 datasets 段有截斷，其餘子命令以 Skill 內 Commands 列表爲準）。
6. 環境與維護：hf env、hf version、hf update。
7. 輸出格式：多數命令支持 --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 管道執行，見上文命令）