Designing the hf CLI as an agent-optimized way to work with the Hub

Summary

The post presents a redesign of hf, the Hugging Face Hub’s official CLI, for both human users and coding agents that download, upload, manage repositories, run Jobs, and administer other Hub resources. The CLI detects agents through environment variables, switches to compact, complete TSV output, and supports explicit human, agent, JSON, and quiet formats; agent mode was introduced in hf v1.9.0. Next-command hints, stderr separation, non-interactive failure messages, retry-safe operations, confirmations, and dry-run previews support multi-step automation without removing human-friendly terminal behavior. Benchmarks report equal-or-better success with roughly 1.3× to 1.8× fewer tokens than curl or the SDK on comparable tasks, and up to 6× fewer on complex workflows; the generated hf-cli skill reduced tool calls by about 30% without reducing token use or improving reliability.

Takeaways

1. 1

   Agent mode emits complete TSV records with full repository IDs, ISO timestamps, all tags, and no ANSI codes or truncation; humans retain aligned, screen-sized tables and status cues.

2. 2

   Many commands provide parameterized next-command hints, while confirmations, --yes, --dry-run, and retry-safe behavior address non-interactive and repeat-execution patterns.

3. 3

   Across benchmark tasks, curl and the SDK used roughly 1.3× to 1.8× as many tokens overall and 2× to 6× as many on multi-step work; the skill cut tool calls by about 30% but did not reduce token use or improve reliability.