hf 是 Hugging Face Hub 的官方命令列介面。您在 Hub 上能透過 Python SDK 完成的任何操作，現在都能在終端機中執行：下載與上傳模型、資料集和 Spaces；建立與管理儲存庫、分支、標籤和拉取請求；在 HF 基礎設施上執行 Jobs；管理 Buckets、Collections、webhooks 和 Inference Endpoints。
多年來，hf CLI 主要為人類使用者而建。然而，它現在正被越來越多的程式代理使用，例如 Claude Code、Codex、Cursor 等。因此，我們重新設計了它，使其能同時服務這兩種受眾。這篇部落格文章總結了我們所做的工作以及如何進行基準測試。
我們發現，在複雜的多步驟任務中，不使用 CLI 的基準方法（代理手動編寫 curl 或 Python SDK）所消耗的 token 數量是 hf CLI 的六倍。AI 代理在 Hub 上的流量我們從 2026 年 4 月開始追蹤 Hub 上的代理使用情況。
hf CLI（及其所基於的 huggingface_hub Python SDK）透過讀取代理設定的環境變數來偵測是否由程式代理驅動：Claude Code 使用 CLAUDECODE/CLAUDE_CODE，Codex 使用 CODEX_SANDBOX，此外還有 Cursor、Gemini、Pi 以及通用的 AI_AGENT。
這個單一訊號有兩個作用：它決定了 CLI 的輸出格式（詳見下文），並為每個 Hub 請求標記 agent/<name> 使用者代理，以便我們能將流量歸因於驅動它的代理。按獨立使用者數量計算，最大的兩個是 Claude Code 和 Codex，遠超其他所有代理，它們也是我們在本文後續進行基準測試的兩個代理。
圖表中的長條代表每個代理的獨立使用者數量；請求量則顯示在副標籤中。僅 Claude Code 就有約 4 萬名使用者和近 4900 萬次請求，Codex 緊隨其後。這些是早期數據（我們從 2026 年 4 月才開始歸因代理流量），但規模已相當可觀，我們預計隨著程式代理成為與 Hub 協作的標準方式，這一數字將持續增長。
為人類和代理而建人類使用者和程式代理對相同的 hf 命令有不同的輸出期望。人類希望獲得豐富的終端機輸出：ANSI 顏色、為適應螢幕而截斷的對齊表格、成功時的綠色 ✅、布林值的 ✔、進度條和文字提示。代理則希望相反：沒有 ANSI 碼、不截斷任何內容、每個值都完整呈現（因為代理能處理比人類更密集的輸出），且保持緊湊和結構化以減少 token 消耗。
代理也無法回應 CLI 提示，並會在逾時後樂於重新執行命令。本節的其餘部分將說明 hf 如何滿足雙方的需求。我們在 hf v1.9.0 中引入了代理模式輸出，並在後續版本中逐步將 CLI 的其餘部分遷移到此模式。一個命令，多種呈現當 hf 自動偵測到代理使用（透過上述環境變數）時，它會以不同的方式呈現相同的命令。
它會自動優化人類或代理的輸出格式，無需傳遞任何旗標：``# human (default in a terminal): aligned table, truncated to fit, with a hint> hf models ls --author Qwen --sort downloads --limit 3ID CREATED_AT DOWNLOADS LIBRARY_NAME LIKES PIPELINE_TAG PRIVATE TAGS------------------------ ---------- --------- ------------ ----- --------------- ------- -------------------------Qwen/Qwen3-0.6B 2025-04-27 21156913 transformers 1285 text-generation transformers, safetens...Qwen/Qwen2.5-1.5B-Ins... 2024-09-17 15143953 transformers 725 text-generation transformers, safetens...Qwen/Qwen3-4B 2025-04-27 14808352 transformers 625 text-generation transformers, safetens...Hint: Use --no-truncate or --format json to display full values.# agent (auto-detected): TSV, full ids + ISO timestamps + every tag, nothing truncated$ hf models ls --author Qwen --sort downloads --limit 3id created_at downloads library_name likes pipeline_tag private tagsQwen/Qwen3-0.6B 2025-04-27T03:40:08+00:00 21156913 transformers 1285 text-generation False ['transformers', 'safetensors', 'qwen3', 'text-generation', 'conversational', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-0.6B-Base', 'base_model:finetune:Qwen/Qwen3-0.6B-Base', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']Qwen/Qwen2.5-1.5B-Instruct 2024-09-17T14:10:29+00:00 15143953 transformers 725 text-generation False['transformers', 'safetensors', 'qwen2', 'text-generation', 'chat', 'conversational', 'en', 'arxiv:2407.10671', 'base_model:Qwen/Qwen2.5-1.5B', 'base_model:finetune:Qwen/Qwen2.5-1.5B', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']Qwen/Qwen3-4B 2025-04-27T03:41:29+00:00 14808352 transformers 625 text-generation False ['transformers', 'safetensors', 'text-generation', 'arxiv:2309.00071', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-4B-Base', 'base_model:finetune:Qwen/Qwen3-4B-Base', 'license:apache-2.0', 'endpoints_compatible', 'deploy:azure', 'region:us']``人類使用者會看到一個對齊的表格，為適應終端機而截斷，並附帶如何查看更多內容的提示，以及狀態的顏色提示（成功時為綠色 ✓，錯誤時為紅色）。
代理則會收到完整的 TSV 格式記錄：完整的儲存庫 ID、完整的 ISO 時間戳、所有標籤、沒有 ANSI 碼、不截斷任何內容，便於解析且 token 消耗低。實際上，我們實作了 .table(...)、.result(...)、.json() 等日誌方法，它們接收原始數據作為輸入並處理格式化。
除了人類和代理模式，我們還引入了 --json 和 --quiet 選項，以便更容易地將命令串聯起來。預設模式會根據上下文自動選擇，但使用者始終可以使用 --format human | agent | json | quiet 強制選擇所需的格式。
下一個命令提示CLI 命令很少單獨執行：一個步驟通常會暗示下一個步驟（例如 git add 之後是 git commit）。許多 hf 命令現在會以提示結尾：精確的下一個要執行的命令，預先填入您剛才使用的 ID，這樣使用者或代理就可以直接連結到下一個步驟，而無需從頭開始摸索。
在背景啟動一個 Job，它會指向其日誌；建立一個 Space，它會指向其啟動狀態：``$ hf jobs run --detach python:3.12 python train.py✓ Job started id: 6f3a1c2e9b url: https://huggingface.co/jobs/celinah/6f3a1c2e9bHint: Use hf jobs logs 6f3a1c2e9b to fetch the logs.``對人類來說，這是一種便利。
對代理而言，這是一條軌道：下一個動作已被命名，並以正確的 ID 參數化，隨時可以執行，因此它只需更少的步驟就能決定要做什麼。錯誤的處理方式也相同，會指出解決方案而不是僅僅失敗：``Error: Not logged in. Run hf auth login first.``提示、警告和錯誤都輸出到標準錯誤 (stderr)，而數據則輸出到標準輸出 (stdout)，因此這些引導資訊不會污染代理正在解析的輸出。
非阻塞且可安全重試hf 絕不會停留在互動式提示符號，等待代理無法按下的按鍵。破壞性命令仍會要求人類確認，但在代理模式下，它會_快速失敗_並在訊息中提供解決方案（Use --yes to skip confirmation.），而 -y/--yes 則會跳過確認。
由於代理會在逾時和失去上下文時重試，因此操作被設計為可安全重複：如果儲存庫已存在，hf repos create --exist-ok 將不執行任何操作；重新執行上傳也會乾淨地重新提交。此外，移動實際數據的命令支援 --dry-run 選項，可在執行前精確顯示將傳輸的內容，這對人類和代理都非常方便，因為兩者都無需承諾進行長時間下載或盲目同步：``# agent mode: a destructive command without --yes refuses, with the fix in the message$ hf repos delete my-org/old-modelError: You are about to permanently delete model 'my-org/old-model'. Proceed? Use --yes to skip confirmation.# commands that move data take --dry-run to preview the transfer first$ hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run[dry-run] Will download 1 files (out of 1) totalling 1.8K.file sizeconfig.json 1.8K`可探索、可預測的命令hf 被設計為可被探索：執行 hf 以查看資源群組，對您需要的群組執行 --help，每個 --help 都會以實際可複製貼上的範例結尾（代理比解析描述更快地匹配這些範例）：`$ hf models ls --help...Examples $ hf models ls --sort downloads --limit 10 $ hf models ls --search "qwen" --author Qwen $ hf models ls Qwen/Qwen3-4B --tree``命令樹保持一致，採用資源 + 動詞的模式，並帶有明顯的別名（hf models ls、hf repos create、hf jobs ps、hf collections delete；list/ls、remove/rm），因此一旦代理學會一個命令，就能推斷出其餘命令。
輸出也具有可組合性：-q 會每行列印一個 ID，以便管道傳遞給下一個命令，而 --json 則提供可交給 jq 處理的內容。``$ hf models ls --author Qwen -q | head -3Qwen/Qwen3-0.6BQwen/Qwen2.5-1.5B-InstructQwen/Qwen3-4B`為程式代理進行 hf CLI 基準測試為了驗證 hf` CLI 對代理是否真的更有效率，我們進行了測量。
我們建立了一個小型評估工具，並透過各種驅動 Hub 的方式，多次執行相同的 Hub 任務集，並根據實際的 Hub 進行每次執行的評分。以下是方法論之前的重點：在兩種代理上，hf CLI 都表現出色，尤其是在複雜的多步驟任務中，它使用的 token 數量明顯更少。
| 代理 | 工具 | 成功率 | token 使用量 | 自我報告錯誤 || --- | --- | --- | --- | --- || Claude Code (Sonnet 4.6) | hf CLI | 0.94 | 基準 | 2 / 163 || | curl / Python SDK | 0.84 | 1.3-1.6 倍 token | 11 / 163 || Codex (GPT-5.5) | hf CLI | 0.93 | 基準 | 3 / 163 || | curl / Python SDK | 0.92 | 1.6-1.8 倍 token | 10 / 163 |hf CLI 的數據行表示已安裝其技能的 CLI；
