Hugging Face hf CLI agent‑optimized redesign cuts token usage and boosts success rates

Hugging Face hf CLI agent‑optimized redesign cuts token usage and boosts success rates

TL;DR

Hugging Face announced that the hf CLI has been redesigned to be agent‑optimized, delivering up to 6× fewer tokens and higher success rates for coding agents such as Claude Code and Codex when performing multi‑step Hub tasks.

Agent traffic on the Hub

Hugging Face began tracking coding‑agent usage of the Hub in April 2026. By detecting environment variables like CLAUDECODE, CODEX_SANDBOX, and the generic AI_AGENT, the hf CLI tags requests with an agent/<name> user‑agent header. The two most active agents are Claude Code (≈ 39.5 k distinct users, 48.6 M requests) and Codex (≈ 34.8 k users, 36.4 M requests). These numbers, collected only since April 2026, already show that agents constitute a substantial and growing portion of Hub traffic.

Built for humans and agents

The CLI now supports two output modes that are selected automatically based on the detected agent environment.

One command, multiple renderings

  • Human mode (default in an interactive terminal) prints aligned tables, truncates long fields, adds ANSI colours, and shows helpful hints.
  • Agent mode (auto‑detected) outputs raw TSV with full identifiers, ISO timestamps, and complete tag lists, without any ANSI codes or truncation. This format is compact for token‑based LLMs and easy to parse.

Both modes share the same underlying logging helpers (.table(), .result(), .json()) and can be forced with --format human|agent|json|quiet.

Next‑command hints

Every successful command now ends with a deterministic hint that shows the exact next CLI call (including IDs) the user or agent should run. Errors also include actionable suggestions, e.g. Use --yes to skip confirmation. Hints are printed to stderr so they never pollute the data stream that agents parse.

Non‑blocking and safe‑to‑retry

  • In agent mode, destructive commands fail fast with a clear fix message instead of prompting for interactive confirmation.
  • Idempotent flags such as --exist-ok and --dry-run make repeated executions safe, which is essential for agents that automatically retry on timeouts.

Discoverable, predictable commands

The CLI follows a consistent resource + verb pattern (hf models ls, hf repos create, hf jobs run). Each --help section ends with copy‑pasteable examples, enabling agents to match commands quickly. Options like -q (one ID per line) and --json further simplify piping and downstream processing.

Benchmarking the hf CLI for coding agents

A dedicated harness evaluated 18 realistic Hub tasks (e.g., aggregating trending models, creating repos with branches/tags, syncing buckets) across two agents—Claude Code (Sonnet 4.6) and Codex (GPT‑5.5). Each task was executed with either:

  1. The hf CLI (with and without its skill), or
  2. Direct curl calls / the huggingface_hub Python SDK.

Each configuration ran 10 repetitions per task, totaling ~1 000 graded runs. Success was verified by re‑querying the live Hub rather than trusting the agents' TASK_COMPLETE markers.

Results summary

Agent Tool Success score Token usage vs. CLI Self‑report errors
Claude Code (Sonnet 4.6) hf CLI 0.94 baseline 2 / 163
curl / SDK 0.84 1.3–1.6× 11 / 163
Codex (GPT‑5.5) hf CLI 0.93 baseline 3 / 163
curl / SDK 0.92 1.6–1.8× 10 / 163

Complex, multi‑step tasks (e.g., bucket sync + prune, repo creation with branch/tag) incurred 2.4× to 6× the token count when using curl/SDK, while simple read‑only operations showed near parity or even a slight advantage for curl/SDK.

Key takeaways

  • The hf CLI consistently achieves higher success rates and dramatically lower token consumption for multi‑step workflows.
  • Even with a stronger LLM (GPT‑5.5), curl/SDK remain wasteful; with a weaker model (Sonnet 4.6) they fail to complete many write operations.

The hf‑CLI skill

Hugging Face ships an auto‑generated skill that lists every command signature, a one‑line description, and essential flags. Agents can load this skill via:

hf skills add            # for most agents
hf skills add --claude   # includes Claude‑specific entries

The skill reduces the average number of tool calls per task from ~10 to ~7 (≈ 30 % fewer), because agents no longer need to probe --help to discover commands. Token usage stays roughly constant, as the skill adds a fixed context slice.

How to try it yourself

  1. Install the 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"
  1. Add the skill for your agent:
hf skills add            # generic agents
hf skills add --claude   # Claude Code
  1. Authenticate (hf auth login) and give the agent a prompt such as:
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.

The agent will generate the appropriate hf commands and execute them with minimal token overhead.

Registering a new agent harness

If you develop a new coding‑agent harness, add its detection entry to agent-harnesses.ts via a small PR. This enables the CLI to recognize the agent, tag its traffic, and apply the agent‑optimized output mode.

Reference: Full benchmark transcripts are available at https://huggingface.co/buckets/celinah/hf-cli-agent-benchmark. The complete command reference lives in the hf CLI guide.

Sources