Designing the hf CLI as an Agent-Optimized Way to Work With the Hub

Key Takeaways

→ hf CLI auto-detects coding agents via env vars and switches to agent-optimized output

→ Agent output is structured TSV: full ids, ISO timestamps, every tag, no ANSI, nothing truncated

→ Benchmarked on 18 Hub tasks x 3 tool setups x 10 runs across Claude Code and Codex

→ curl/Python SDK burn roughly 1.3-1.8x tokens overall, and 2-6x on multi-step tasks

→ Installing the hf-cli skill cut mean tool calls from about 10.4 to 6.9 per task

→ Since April 2026 the Hub has attributed traffic to agents; Claude Code leads with ~39.5k users

Hugging Face has rebuilt the hf CLI — the official command-line entrypoint to the Hub — so that the same commands now serve two very different audiences at once: humans at a terminal and the coding agents increasingly driving the Hub. The redesign was driven by traffic: agents had become real users, and cutting their token cost changed how the CLI works.

Agents Are Now First-Class Users

Hugging Face began attributing agent traffic in April 2026, reading environment variables agents set to detect the driver. The two largest by distinct users are Claude Code (about 39.5k users, 48.6M requests) and Codex (about 34.8k users, 36.4M requests), with antigravity, cursor-cli, openclaw, cursor, gemini, and pi behind them. That signal does double duty: it switches the CLI into agent mode and tags every request with its originating agent.

One Command, Two Renderings

The design centers on a single command producing two outputs:

Human mode — aligned tables truncated to fit, ANSI color, progress bars, prose hints, a green check on success
Agent mode — tab-separated values with full ids, ISO timestamps, every tag, no ANSI codes, nothing truncated, light on tokens

The format is auto-selected from context, but --format human | agent | json | quiet forces any rendering. Commands also end with next-command hints that name the exact follow-up with the right ids, and errors tell agents the fix — for example, run hf auth login instead of failing silently.

hf never sits on an interactive prompt an agent cannot answer. Destructive commands fail fast with Use --yes to skip confirmation., and --dry-run previews any transfer of real data before it happens. Operations are safe to retry: --exist-ok makes repo creation idempotent, and re-uploads commit cleanly.

Benchmarking Against curl and the SDK

Hugging Face ran 18 non-trivial Hub tasks across two agents, three tooling setups, ten repetitions, and roughly a thousand graded runs — re-querying the live Hub rather than trusting agent self-reports. Results:

Claude Code with Sonnet 4.6: 0.94 success with hf vs 0.84 with curl/Python SDK
Codex with GPT-5.5: 0.93 vs 0.92, while burn fewer tokens
Simple one-shot reads were near parity, but multi-step jobs cost curl/SDK 2x to 6x the tokens

The Skill

hf ships a skill — an auto-generated, release-synced reference of the whole command surface that agents load as context. Installing it cut mean tool calls per task from about 10.4 to 6.9 on Claude Code and 10.1 to 7.3 on Codex; closer to 30 percent fewer probes of --help.

Try It Yourself

Install with the scripts at hf.co/cli, add the skill, log in with hf auth login, and hand your agent a Hub task. Hugging Face’s argument is simple: agents get more useful when their tools are designed for them — and a Hub that works well for agents works better for the humans driving them.

Frequently Asked Questions

What is the hf CLI?

hf is the official command-line entrypoint to the Hugging Face Hub. It lets you download and upload models, datasets, and Spaces; manage repos, branches, tags, PRs, Jobs, Buckets, webhooks, and Inference Endpoints — everything the Python SDK can do, from the terminal.

How does the hf CLI detect that an agent is using it?

It reads environment variables agents set, such as CLAUDECODE or CODEX_SANDBOX, plus a universal AI_AGENT variable. The signal changes the output format and tags the Hub request with an agent user-agent so traffic can be attributed.

Is the hf CLI more efficient for AI agents?

In Hugging Face's benchmark, yes. On 18 real Hub tasks, agents using the hf CLI matched or beat curl/Python-SDK success while using roughly 1.3-1.8 times fewer tokens overall and 2 to 6 times fewer on complex multi-step jobs.

How do I install the hf CLI and its agent skill?

On macOS and Linux run the install script from hf.co/cli, or use the PowerShell installer on Windows. Then run hf skills add to install the auto-generated command reference for Codex, Cursor, OpenCode, and others, or hf skills add --claude to include Claude Code.