hf是 Hugging Face Hub 的官方命令行入口。你在 Hub 上通过 Python SDK 能做的任何事情，都可以在终端中完成：下载和上传模型、数据集与 Spaces；创建和管理仓库、分支、标签与拉取请求；在 HF 基础设施上运行 Jobs；管理 Buckets、Collections、webhooks 和 Inference Endpoints。该hfCLI 多年来主要是为我们的用户而构建的。但如今它越来越多地被编程智能体所使用：Claude Code、Codex、Cursor 等等。因此我们重新构建了它，使其能同时服务于这两类受众。这篇博文总结了我们所做的工作，以及我们如何对其进行基准测试。我们发现，在复杂的多步骤任务上，无 CLI 的基线方案（智能体手工拼凑curl或使用 Python SDK）消耗的 token 最多可达6 倍于使用hfCLI 的量。

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 请求打上 agent/<name> user-agent 标签，从而让我们能够将流量归因于驱动它的智能体。按去重用户数计算，规模最大的两个是 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 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，而每个 --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 任务反复运行了多次，每次运行都对照实时 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× tokens	11 / 163
Codex (GPT-5.5)	hf CLI	0.93	基线	3 / 163
	curl / Python SDK	0.92	1.6-1.8× tokens	10 / 163

（自报错误 = 智能体在 17 个可解任务上报告成功，但 Hub 的说法并非如此。hf CLI 行是安装了其技能的 CLI；该技能在裸 CLI 之上额外增加的内容（主要是更少的工具调用）在下方技能部分中单独列出。代表性对话记录发布在此存储桶中。）

设置

我们定义了18 个非平凡的 Hub 任务。不是"下载一个文件"，而是你实际会提出的那种需求：聚合某个热门组织的模型、检查某个仓库的文件及其大小、按包含/排除规则上传文件夹、删除文件、跨仓库复制文件、发起一个添加许可证的 PR、创建一个带分支和标签的仓库、同步并清理存储桶、构建一个 collection。每个任务都交给一个全新的编码智能体，且只有一种与 Hub 对话的方式：

• hf CLI，或者
• curl / Python SDK：完全没有 hf CLI，因此智能体只能退回到针对 REST API 的 curl 或 huggingface_hub Python 库。

我们在两种配置下运行 hf CLI，分别带和不带它的技能（一份生成的命令参考，我们会在专门的一节中再回到它）。但下面最重要的对比其实只是 hf CLI 对比 curl / SDK；技能带来的增量效果小到足以让我们把它单独拆出来，而不是硬塞进主要结果里。

配置是刻意保持干净的：每次运行都用全新实例，没有自定义 MCP 服务器，没有 CLAUDE.md 或 AGENTS.md，上下文中没有任何会诱导行为的东西。任务和工具被放进同一个提示词里，智能体以一个 TASK_COMPLETE 或 TASK_FAILED 标记结束，但我们不信任这个标记（智能体会对根本没落地的工作报告成功），所以我们通过重新查询实时 Hub来独立给每次运行评分：分支真的创建了吗，文件真的删掉了吗，存储桶存在吗？每个任务/工具组合运行 10 次，因为编程智能体是非确定性的，每个智能体大约 520 次运行（18 个任务 × 3 个工具 × 10 次重复，减去某个可计费 Jobs 任务的上限），总共有约 1,000 次评分运行。我们把整个流程跑了两遍，用的是两个最流行的编程智能体（Claude Code 搭配 Sonnet 4.6，以及 OpenAI Codex 搭配 GPT-5.5）。

结果

下面两张图拆解了上表。首先是 Sonnet 上的任务成功率，也就是 curl 和 SDK 最吃力的那个智能体：

如果没有 CLI，curl 和 SDK 会落后十分，因为在 Sonnet 上它们根本无法完成部分工作（主要是写入操作），而 hf CLI 则能顺利完成这些任务。

第二张图展示了 token 对 GPT-5.5 的影响，按任务细分。每根柱子是同一任务上 curl/SDK 的 token 数除以 CLI 的 token 数，因此 2.4× 意味着非 hf 版本完成同样的事情消耗了 2.4 倍的 token：

在一次性的读取操作中（统计数据行数、批量获取元数据），curl 和 SDK 表现良好，有时甚至更轻量。但随着任务变得更加复杂、涉及多个相互依赖的步骤，智能体不得不手工编写整条 REST 调用链（或者翻找 SDK），成本随之飙升：在创建带分支和标签的仓库、删除文件、跨仓库复制或同步存储桶等操作上，达到 CLI 的 2.4 倍到 6 倍。hf CLI 让智能体可以将任务表达为几条更高层的命令，而不必精心构造复杂的工作流。

关键发现

• hf CLI 远比 curl 或 SDK 精简。在相同任务上，以相当或更好的成功率，curl 和 SDK 消耗的 token 量大约是其 1.3 倍到 1.8 倍。在简单的读取操作上它们表现尚可，但在真正的多步骤工作中，代价高达2 倍到 6 倍：CLI 将一连串 REST 调用组合成几条高层命令，而 curl 或 SDK 每次运行都要重新手工推导整条调用链。
• 在更强的模型上，curl 和 SDK 能正常工作，但依然很浪费。在 Sonnet 上，它们无法完成部分工作（主要是写入操作）；在 GPT-5.5 上，它们大多能成功，能正确地手工编写 REST 调用（或使用 SDK），但付出的 token 开销仍远高于 CLI。

hf-cli 技能

hf附带了一个技能：一份整个命令面的紧凑参考，供 AI 智能体作为上下文加载。它自动生成自实时的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

它能带来什么好处？主要是，智能体不再靠猜了。最直观的一个视角是每次运行需要执行多少条命令，有技能和没有技能的对比：

在两个智能体上，每个任务大约从十条命令降到约七条，工具调用大约减少了 30%。这是因为智能体不再需要反复试探 --help 来找到正确的命令和参数。这项技能不会削减你的 token 开销，因为它会在上下文前面固定附加一段信息，所以同一任务下 token 数量基本持平，甚至略有上升。这项技能也不会让 CLI 变得更可靠，但它能帮助智能体把时间花在执行你的任务上，而不是去摸索这个工具怎么用。在使用 hf 搭配本地模型时，这一点可能特别有帮助。

我们在全新会话中运行了每一项任务，因此该技能在每项任务上都要付出其上下文成本。在真实的多任务会话中，这一成本会被摊薄（智能体只需学习一次命令界面），所以 token 情况在那里很可能会改善；我们没有测量那种情况。

自己动手试试

我们对这一切做了基准测试，因为我们认为这很重要。智能体正在成为 Hub 的真实用户：它们训练模型、构建和清理数据集，并以 Spaces 的形式发布 demo，几乎总是代表某个人来完成。一个对智能体友好的 Hub，也是一个对使用这些智能体的人更友好的 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

然后把你的智能体指向 Hub，让它开始工作。确保你已登录（hf auth login），然后给它一个类似这样的提示词：

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 CLI 指南。

注册一个智能体运行框架

正在构建智能体运行框架？快去注册吧！这样 hf 才能学会检测它，Hub 也才能将其流量归因到你的运行框架。你只需提交一个小型 PR，向 agent-harnesses.ts 添加一个条目即可。更多详情请阅读 注册你的智能体运行框架 指南。