MLOps

Designing Tools for AI Agents: Lessons from the hf CLI

Hugging Face rebuilt its hf CLI for AI agents: up to 6x fewer tokens, machine output and guardrails. What it means for the internal tools your team owns.

Designing Tools for AI Agents: Lessons from the hf CLI

Designing Tools for AI Agents: Lessons from the hf CLI

Here is a question almost no one was asking two years ago: when you write a command-line tool, who is actually going to type the commands? For two decades the answer was obvious — a human, so you gave them color, aligned tables, chatty help text, and a confirmation prompt before anything destructive. In 2026 that assumption is breaking. A growing share of commands is now issued by coding agents such as Claude Code, Codex, and Cursor. Hugging Face has just published a detailed write-up of rebuilding its CLI for that reality, and the lessons reach far beyond the Hub.

For any team putting agents into production, the takeaway is concrete: a tool designed for an agent is not the same tool you would design for a human. And the gap is measurable — in tokens, in success rate, and in cloud bills.

The context

Hugging Face renamed huggingface-cli to hf in mid-2025, reorganizing commands into a clean hf <resource> <action> shape (hf models ls, hf repos create, hf jobs ps). That started as housekeeping for humans. But in April 2026 the team began instrumenting traffic and saw the scale of what was happening: over the measured period, Claude Code accounted for 39,500 distinct users and 48.6 million requests, and Codex for 34,800 users and 36.4 million requests. The tool was no longer mostly driven by human hands.

So they rebuilt hf to serve both audiences at once, without degrading the human experience. The result, documented in Designing the hf CLI as an agent-optimized way to work with the Hub, is a small masterclass in machine ergonomics.

One CLI that speaks two languages

The same command renders differently depending on who runs it — with no extra flag. In human mode, hf models ls prints an aligned, truncated, colored table plus a hint like "Use --no-truncate to display full values." In agent mode — detected automatically — the same command returns raw TSV: full IDs, ISO 8601 timestamps, every tag, no ANSI codes, nothing truncated, and no prose to trip up a parser.

Detection relies on environment variables: CLAUDECODE/CLAUDE_CODE for Claude Code, CODEX_SANDBOX for Codex, plus Cursor, Gemini, Pi, and a universal AI_AGENT. Each Hub request is then tagged agent/<name> for traffic attribution. When auto-detection isn't enough, an explicit flag covers all four renderings: --format human | agent | json | quiet.

Data on stdout, guidance on stderr

The detail that matters most is also the simplest: data goes to stdout, while hints, warnings, and errors go to stderr. An agent parsing the output never ends up with a help message glued to the data it is trying to read. It is an ancient Unix discipline, yet plenty of modern tools forgot it — and paid for it with brittle parsers and agents that hallucinate when the format drifts.

Rails, not prompts

An agent cannot press a key to confirm. A CLI that stops at an interactive prompt is a dead end. The hf redesign answers with three principles.

First, rails: every command ends by naming the next command to run, pre-filled with the IDs you just used. After hf jobs run, the tool prints "Use hf jobs logs 6f3a1c2e9b to fetch the logs." The agent doesn't have to guess or reconstruct an identifier — the next step is named and parameterized.

Second, fail fast and explicit. In agent mode, destructive commands don't block; they fail immediately with the fix in the message ("Use --yes to skip confirmation"). The -y/--yes flag waives confirmation when the agent is allowed to. Errors name the remedy: "Not logged in. Run hf auth login first."

Third, idempotence. hf repos create --exist-ok is a no-op if the repo already exists; re-running an upload re-commits cleanly; and any data-moving command accepts --dry-run to announce its effect before executing. Together these make an agent's retries safe by construction.

Composing and scripting

A good agent tool also has to compose. hf exposes a -q flag that returns just one ID per line, ready to pipe into head, xargs, or a loop: hf models ls --author Qwen -q | head -3. For structured processing, --format json produces output you can feed straight to jq. That dual output — plain text for piping, JSON for parsing — spares the agent from reinventing a brittle regex extractor every time.

The detail matters because an agent works in chains: it lists, filters, then acts on the result. If every link returns a clean, stable format, the agent stays on rails; if a single one emits a colored, truncated table, the whole chain derails. That is the difference between a tool an agent drives in three commands and one it fumbles through in fifteen. The same discipline applies to any API you expose: predictable shapes beat pretty ones the moment a machine is the consumer.

The real metric: tokens

This is where the argument turns economic. Hugging Face compared three conditions — hf CLI with a "skill," hf CLI alone, and the curl / Python SDK baseline — across 18 non-trivial Hub tasks, with 10 runs per condition, roughly 1,000 graded runs. Grading was done by re-querying the live Hub, not by trusting the agent's self-report.

The headline: on multi-step tasks, the no-CLI baseline burns up to 6× as many tokens as hf. The per-task breakdown is striking — bucket create + sync + prune: 6.0×; ranking organizations by trending models: 4.1×; repo create + branch + tag: 2.4×. Conversely, for simple one-shot reads the CLI is slightly more expensive (0.3–0.5×): the optimization targets real workflows, not trivial calls.

Quality tracks cost. Claude Code (Sonnet 4.6) scores 0.94 with hf versus 0.84 with curl/SDK. More subtly, the CLI cuts false success reports: Claude Code is wrong on 2 of 163 tasks with hf, versus 11 of 163 with curl/SDK. For a production team, that last number may be the most important one — an agent that believes it succeeded when it actually failed is far more dangerous than one that fails out loud.

The "skill" as on-demand context

The final stage is an hf-cli skill: an auto-generated command reference the agent loads into context. It cuts commands per run by about 30% (Claude Code drops from 10.4 to 6.9 commands per task; Codex from 10.1 to 7.3). You install it with hf skills add or hf skills add --claude. The broader idea — hand the agent a concise map of the tool instead of letting it fumble — transfers to any internal tool you own.

What it means for AI teams

The hf CLI is just one example, but the signal is unmistakable: your internal tools will be driven by agents, and their design is now a production-engineering concern. Three concrete implications.

Agent cost is largely tooling cost. If an agent spends 6× more tokens on a task because your in-house CLI emits truncated JSON and interactive prompts, you pay that debt on every run. Auditing tools through the lens of "how many tokens for task X" is now as legitimate as profiling a SQL query.

Reliability is machine ergonomics. Separating stdout/stderr, naming the fix in error messages, making operations idempotent, and offering --dry-run are no longer niceties — they are the preconditions for an agent to retry without breaking things. This is exactly the productionization work SeedVision does when rolling agents out to production.

Observability has to follow the agent. Hugging Face's agent/<name> tagging is not a gimmick: knowing what share of your traffic comes from agents, and which ones, is the basis for sizing quotas, spotting expensive loops, and billing correctly. If you expose tools or APIs, plan for per-agent attribution now.

In short

  • Hugging Face rebuilt its hf CLI to serve humans and agents from one command base, after measuring tens of millions of requests from Claude Code and Codex.
  • The key principles: machine-readable output (TSV, ISO, no ANSI), data on stdout and guidance on stderr, rails to the next command, fail-fast destructive actions, idempotence, and --dry-run.
  • The payoff is measurable: up to 6× fewer tokens on multi-step workflows, higher success rates, and half as many false success reports.
  • For AI teams: an agent's cost is first a tooling cost — design your CLIs and APIs for the agent that will drive them.

Industrialising AI agents? SeedVision offers 3-5 day AI audits and 15-30 day production rollouts. See the packages or book a 30-min call.

Cover photo: Photo by Jake Walker on Unsplash.