将 hf CLI 设计成面向代理优化的 Hub 操作工具

hf 是 Hugging Face Hub 的官方命令行入口。通过 Python SDK 能在 Hub 完成的操作，都可以从终端完成：下载和上传模型、数据集、Space；创建和管理仓库、分支、标签与拉取请求；在 HF 基础设施上运行 Job；管理 Bucket、Collection、Webhook 和推理端点。

多年来，hf CLI 主要面向用户构建。但 Claude Code、Codex、Cursor 等编码代理越来越多地使用它。因此，我们重新设计它，让人与代理都能获得良好体验。本文总结改动与基准测试。我们发现，在复杂多步骤任务上，不使用 CLI、由代理自行编写 curl 或 Python SDK 调用的基线，token 用量最高达到 hf CLI 的 6 倍。

Hub 上的 AI 代理流量

我们从 2026 年 4 月开始跟踪代理使用 Hub 的情况。hf CLI 及其底层 huggingface_hub Python SDK 读取代理设置的环境变量，检测是否由编码代理驱动：Claude Code 的 CLAUDECODE／CLAUDE_CODE，Codex 的 CODEX_SANDBOX，以及 Cursor、Gemini、Pi 和通用 AI_AGENT 信号。

同一信号承担两件事：决定 CLI 的输出方式，以及给每次 Hub 请求的 user-agent 加上 agent/<name>，使流量可归因到相应代理。按独立用户数，Claude Code 与 Codex 明显领先，也是本文后续测试的两个代理。

柱形表示各代理的独立用户数，下方标签表示请求量。Claude Code 约有 4 万用户、近 4900 万请求，Codex 紧随其后。这些是早期数据，归因统计才从 2026 年 4 月开始，但规模已经很可观。随着编码代理成为常见 Hub 操作方式，我们预计它会继续增长。

同时服务人与代理

面对相同 hf 命令，人与编码代理期待的输出不同。人需要丰富的终端输出：ANSI 颜色、为屏幕宽度填充和截断的表格、成功时绿色 ✅、布尔值的 ✔、进度条与文字提示。代理恰好相反：不要 ANSI，不要截断，每个值完整显示；它能处理比人密集得多的输出，但仍应紧凑、结构化，以节省 token。代理也无法回答交互式提示，并且会在超时后重新运行命令。

本节介绍 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 3
ID                       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 3
id      created_at      downloads       library_name    likes   pipeline_tag    private tags
Qwen/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/6f3a1c2e9b
Hint: 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-model
Error: 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         size
config.json  1.8K

易发现、可预测的命令

hf 支持逐步探索：运行 hf 查看资源组，对所需组运行 --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 -3
Qwen/Qwen3-0.6B
Qwen/Qwen2.5-1.5B-Instruct
Qwen/Qwen3-4B

面向编码代理的 hf CLI 基准测试

为确定 hf CLI 是否真的更高效，我们进行了测量。我们构建小型评估框架，反复用不同 Hub 操作方式运行相同任务，并对照实时 Hub 结果评分。先说主要结论：两个代理上 hf CLI 均领先，在复杂多步骤任务中节省 token 最明显。

“自报错误”指在 17 个可解任务上，代理报告成功，但 Hub 实际状态不支持该报告。hf CLI 行使用已安装技能的 CLI。技能相对于裸 CLI 的增益主要是减少工具调用，见下方技能一节。代表性对话记录发布在 基准测试 Bucket。

测试设置

我们定义了 18 个非平凡 Hub 任务，不只是“下载一个文件”，而是真实请求：汇总热门组织的模型、检查仓库文件及大小、按包含／排除规则上传文件夹、删除文件、跨仓库复制文件、创建添加许可证的 PR、创建带分支和标签的仓库、同步并清理 Bucket、建立 Collection。每个任务使用全新的编码代理，并只允许一种操作 Hub 的方式：

• hf CLI；或
• curl／Python SDK，完全不提供 hf CLI，让代理调用 REST API 或 huggingface_hub Python 库。

hf CLI 又分安装和不安装技能两种配置，技能是一份生成的命令参考。主要比较仍是 hf CLI 与 curl／SDK；技能增益相对较小，因此单独讨论。

配置刻意保持干净：每次全新实例，没有自定义 MCP 服务，没有 CLAUDE.md 或 AGENTS.md，也没有引导行为的上下文。任务与工具写入一条提示词。代理最后给出 TASK_COMPLETE 或 TASK_FAILED，但我们不相信这个标记，因为代理可能把未真正完成的操作报告为成功。

我们通过重新查询实时 Hub独立评分：分支是否真的创建？文件是否真的删除？Bucket 是否存在？编码代理具有非确定性，因此每个任务／工具组合重复 10 次。每个代理约 520 次运行，即 18 任务 × 3 工具 × 10 次，减去一个计费 Job 任务的次数限制；总计约 1000 次评分。整套测试分别运行于最常用的 Claude Code（Sonnet 4.6）与 OpenAI Codex（GPT-5.5）。

结果

下面两张图展开表格数据。先看 curl 和 SDK 最吃力的 Sonnet：

没有 CLI 时，curl 和 SDK 落后 10 个百分点，因为 Sonnet 无法完成某些任务，主要是写入；hf CLI 则能完成。

第二张图按任务展示 GPT-5.5 的 token 影响。每根柱是同一任务中 curl／SDK token 用量除以 CLI 用量，因此 2.4× 表示非 hf 方式完成相同任务消耗 2.4 倍 token：

一次性读取任务，例如统计数据集行数、批量读取元数据，curl 和 SDK 表现不错，有时更节省。但任务更复杂、包含多个依赖步骤时，代理必须自行组合整条 REST 调用链或查找 SDK，成本迅速增长：创建带分支和标签的仓库、删除文件、跨仓库复制、同步 Bucket 的 token 用量达到 CLI 的 2.4–6 倍。hf CLI 让代理用几个高层命令表达任务，无需构造复杂流程。

关键发现

• hf CLI 比 curl 或 SDK 节省得多。同任务、成功率相当或更高时，curl 和 SDK 大约消耗 1.3–1.8 倍 token。简单读取没有问题，但真实多步骤任务要付出 2–6 倍：CLI 把 REST 调用链组合为少量高层命令，curl／SDK 则每次重新人工推导。
• 更强模型能用 curl 和 SDK 完成任务，但仍然浪费。Sonnet 有些步骤无法完成，主要是写入；GPT-5.5 大多成功，能正确构造 REST 调用或使用 SDK，但 token 成本仍远高于 CLI。

hf-cli 技能

hf 随附技能，是代理加载到上下文中的紧凑完整命令参考。它从实时命令树自动生成，每个命令一行，列出签名、简述和重要标志，按资源分组，并附通用选项小词汇表。它有意略去不言自明的标志，保持简洁，减少上下文负担，每次发布都重新生成。运行 hf skills preview 查看，或安装：

# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude

它的主要价值是让代理停止猜测。最直观的指标是安装前后每次运行需要多少命令：

两个代理都从每任务约 10 条命令降到约 7 条，工具调用减少约 30%。原因是不用反复查 --help 寻找命令与参数。技能不会降低 token 账单，因为它往上下文预先加入固定信息，同任务 token 用量保持接近或略增。它也不会让 CLI 更可靠，但能让代理把时间用在执行任务，而非探索工具。对使用本地模型的 hf 用户，这可能尤其有帮助。

测试中每个任务都使用全新会话，因此每次都承担技能上下文成本。真实多任务会话中，代理只需学习命令界面一次，该成本会摊薄，token 情况可能更好；我们没有测量这种情况。

亲自试试

我们做基准测试，是因为认为这很重要。代理正成为 Hub 的真实用户：训练模型、构建和清理数据集，并以 Space 发布演示，几乎总是代表某个人行动。适合代理的 Hub 也更适合使用代理的人。工具越好，代理越能替你完成工作。

如果代理要操作 Hugging Face Hub，我们推荐给它 hf CLI：

# macOS / Linux
curl -LsSf https://hf.co/cli/install.sh | bash

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

再提供技能，让代理从第一轮就知道全部命令：

hf skills add            # Codex, Cursor, OpenCode, Pi and other agents that load skills from .agents/skills
hf skills add --claude   # the above + Claude Code

确认已经登录（hf auth login），然后让代理操作 Hub，例如给出以下提示词：

Use `hf` to list my Hugging Face Hub models, datasets, and Spaces.
Take a look at how I am currently using the Hub and suggest a few ways you could help me.

该提示词的意思是：“用 hf 列出我在 Hugging Face Hub 上的模型、数据集和 Space，看看我目前如何使用 Hub，并建议几种你能帮助我的方式。”代理会自行找出命令，带回有用结果。

完整命令参考见 hf CLI 指南。

注册代理运行框架

如果正在构建代理运行框架，请注册它！这样 hf 才能检测它，Hub 才能把流量归因到它。只需提交小型 PR，向 agent-harnesses.ts 增加条目。详细说明见 注册代理运行框架指南。

来源与版权

作者 Célina Hanouti、Lucain Pouget；原文 Designing the hf CLI as an agent-optimized way to work with the Hub，2026 年 6 月 4 日，Hugging Face Blog。本中文版本依据转载授权翻译。代码、命令、基准条件及数字保留原文，未独立运行测试。