에이전트에 최적화된 Hub 작업 방식으로서의 hf CLI 설계

hf는 Hugging Face Hub의 공식 커맨드 라인 엔트리포인트 (command-line entrypoint)입니다. Python SDK를 통해 Hub에서 할 수 있는 모든 작업은 터미널에서도 수행할 수 있습니다: 모델, 데이터셋 (datasets), Spaces 다운로드 및 업로드; 리포지토리 (repos), 브랜치 (branches), 태그 (tags), 풀 리퀘스트 (pull requests) 생성 및 관리; HF 인프라에서 잡 (Jobs) 실행; 버킷 (Buckets), 컬렉션 (Collections), 웹훅 (webhooks), 인퍼런스 엔드포인트 (Inference Endpoints) 관리.

hf CLI는 지난 수년간 주로 사용자들을 위해 구축되어 왔습니다. 하지만 이제는 Claude Code, Codex, Cursor 등 **코딩 에이전트 (coding agents)**에 의해 점점 더 많이 사용되고 있습니다. 그래서 우리는 두 대상 모두를 동시에 만족시킬 수 있도록 CLI를 재구축했습니다. 이 블로그 포스트는 우리가 무엇을 했는지, 그리고 어떻게 벤치마크 (benchmark)를 수행했는지를 요약합니다. 우리는 복잡한 다단계 작업에서 CLI를 사용하지 않는 베이스라인 (no-CLI baseline, 에이전트가 curl이나 Python SDK를 직접 구현하여 사용하는 방식)이 hf CLI를 사용할 때보다 **최대 6배 더 많은 토큰 (tokens)**을 사용한다는 것을 발견했습니다.

우리는 2026년 4월부터 에이전트의 Hub 사용량을 추적하기 시작했습니다. hf CLI (및 이를 기반으로 구축된 huggingface_hub Python SDK)는 에이전트가 설정하는 환경 변수 (environment variables)를 읽음으로써 코딩 에이전트가 이를 구동하고 있는지 감지합니다: Claude Code의 경우 CLAUDECODE / CLAUDE_CODE, Codex의 경우 CODEX_SANDBOX, 그리고 Cursor, Gemini, Pi, 그리고 범용적인 AI_AGENT가 있습니다. 이 단일 신호는 두 가지 역할을 수행합니다: CLI의 출력 형식을 조정하고 (이에 대해서는 아래에서 자세히 설명), 각 Hub 요청에 agent/<name> 사용자 에이전트 (user-agent) 태그를 붙여 해당 요청을 구동하는 에이전트의 트래픽으로 귀속시킬 수 있게 합니다. 개별 사용자 수 기준으로 가장 큰 두 에이전트는 다른 모든 것들을 훨씬 앞서는 Claude Code와 Codex이며, 이들은 이 글의 후반부에서 벤치마크할 두 에이전트입니다.

막대 그래프는 에이전트당 개별 사용자 수를 나타내며, 하단 레이블은 요청 볼륨 (request volume)을 나타냅니다. Claude Code 하나만으로도 약 4만 명의 사용자와 거의 4,900만 건의 요청을 기록하고 있으며, Codex가 그 뒤를 바짝 쫓고 있습니다. 이는 초기 수치이지만 (우리는 2026년 4월에 에이전트 트래픽 귀속을 시작했습니다), 규모가 이미 상당하며 코딩 에이전트가 Hub를 사용하는 표준적인 방식이 됨에 따라 계속 성장할 것으로 예상합니다.

인간과 코딩 에이전트는 동일한 hf에 대해 서로 다른 출력을 기대합니다.

명령어들입니다. 인간은 풍부한 터미널 출력을 원합니다: ANSI 색상, 화면 크기에 맞춰 잘린 패딩된 표, 성공 시의 초록색 ✅, 불리언(boolean) 값에 대한 ✔, 진행 표시줄(progress bars), 그리고 설명적인 힌트 같은 것들 말이죠. 반면 에이전트(agent)는 그 반대의 것을 원합니다: ANSI 색상 없음, 잘린 내용 없음, 에이전트는 인간보다 훨씬 밀도 높은 출력을 처리할 수 있으므로 모든 값을 온전하게 제공하되, 토큰(token) 사용량을 줄이기 위해 압축되고 구조화된 형태를 유지해야 합니다. 또한 에이전트는 CLI 프롬프트(prompt)에 답할 수 없으며, 타임아웃(timeout)이 발생하면 기꺼이 명령어를 다시 실행할 것입니다. 이 섹션의 나머지 내용은 hf가 어떻게 각 측면에 필요한 것을 제공하는지에 대해 다룹니다. 우리는 hf v1.9.0에서 에이전트 모드(agent-mode) 출력을 도입했으며, 이후 릴리스(release)를 통해 나머지 CLI를 점진적으로 이 모드로 마이그레이션(migrating)하고 있습니다.

hf가 (위에서 언급한 환경 변수를 통해) 에이전트 사용을 자동 감지하면, 동일한 명령어를 다르게 렌더링(render)합니다. 플래그(flag)를 전달하지 않고도 인간 또는 에이전트를 위해 출력 형식을 최적화합니다:

# 인간 (터미널 기본값): 정렬된 표, 화면에 맞춰 잘림, 힌트 포함
> hf models ls --author Qwen --sort downloads --limit 3
ID CREATED_AT DOWNLOADS LIBRARY_NAME LIKES PIPELINE_TAG PRIVATE TAGS
...

인간은 터미널에 맞춰 잘린 정렬된 표와 함께, 더 많은 정보를 보는 방법에 대한 힌트, 그리고 상태에 따른 색상 신호(성공 시 초록색 ✓, 에러 시 빨간색)를 받습니다. 에이전트는 TSV 형식의 완전한 레코드를 받습니다: 전체 리포지토리(repo) ID, 전체 ISO 타임스탬프(timestamp), 모든 태그, ANSI 코드 없음, 잘린 내용 없음, 파싱(parse)하기 깔끔하고 토큰 사용량이 적은 형태입니다.

실제로 우리는 원시 데이터(raw data)를 입력으로 받아 포맷팅을 처리하는 .table(...), .result(...), .json() 등의 로깅 메서드(logging methods)를 구현했습니다. 인간 및 에이전트 모드 외에도, 명령어들을 파이프(pipe)로 연결하기 쉽게 만들기 위해 --json 및 --quiet 옵션을 도입했습니다. 기본 모드는 컨텍스트(context)에 따라 자동으로 선택되지만, 사용자는 언제든지 --format human | agent | json | quiet를 사용하여 원하는 형식을 강제할 수 있습니다.

CLI 명령어는 단독으로 실행되는 경우가 드뭅니다. 한 단계는 보통 다음 단계를 암시합니다 (git add 후 git commit). 많은 hf

많은 hf 명령어는 이제 **힌트 (hint)**로 끝납니다. 즉, 방금 사용한 ID가 미리 채워진 채로 실행해야 할 정확한 다음 명령어를 제공하여, 사용자나 에이전트가 처음부터 고민할 필요 없이 바로 다음 단계로 체이닝 (chaining) 할 수 있게 합니다. 백그라운드에서 작업을 시작하면 해당 작업의 로그를 안내하고, Space를 생성하면 부팅 상태를 안내합니다:

$ hf jobs run --detach python:3.12 python train.py
✓ Job started
id: 6f3a1c2e9b
...

사람에게 이것은 편의성이지만, 에이전트에게는 레일 (rail)과 같습니다. 다음 동작이 명명되어 있고, 올바른 ID로 매개변수화되어 실행 준비가 되어 있으므로, 무엇을 해야 할지 파악하는 데 필요한 단계가 줄어듭니다. 에러 (Error) 또한 동일한 방식으로 작동하여, 단순히 실패하는 대신 해결 방법을 명시합니다:

Error: Not logged in. Run `hf auth login` first.

힌트 (hint), 경고 (warning), 에러 (error)는 모두 stderr (표준 에러)로 전송되는 반면, 데이터는 stdout (표준 출력)으로 전송됩니다. 따라서 이러한 안내 사항들이 에이전트가 파싱 (parsing) 하는 출력값을 오염시키지 않습니다.

hf는 에이전트가 누를 수 없는 키를 기다리며 대화형 프롬프트 (interactive prompt)에 멈춰 서 있는 일이 절대 없습니다. 파괴적인 명령은 여전히 사람에게 확인을 요청하지만, 에이전트 모드에서는 메시지에 해결 방법을 포함하여 빠르게 실패 (fails fast) 합니다 (Use --yes to skip confirmation. 사용 권장). 또한 -y 또는 --yes 옵션으로 이를 건너뛸 수 있습니다. 그리고 에이전트는 타임아웃 (timeout)이나 컨텍스트 (context) 유실 시 재시도하기 때문에, 모든 작업은 반복 실행해도 안전하도록 설계되었습니다. 예를 들어 hf repos create --exist-ok는 리포지토리 (repo)가 이미 존재하면 아무 작업도 수행하지 않으며 (no-op), 업로드를 다시 실행하면 깔끔하게 재커밋 (re-commits) 됩니다. 이와 별개로, 실제 데이터를 이동하는 명령어들은 실행 전에 무엇을 전송할지 정확히 보여주는 --dry-run 옵션을 제공합니다. 이는 긴 다운로드나 맹목적인 동기화 (sync)를 감수할 필요가 없으므로 사람과 에이전트 모두에게 유용합니다:

# 에이전트 모드: --yes가 없는 파괴적인 명령은 거부되며, 메시지에 해결 방법이 포함됨
$ 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.
...

hf는 탐색 (probe) 가능하도록 구축되었습니다. 리소스 그룹 (resource groups)을 보려면 hf를 실행하고, 필요한 명령어에 --help를 실행하면 되며, 모든 --help

ends with real, copy-pasteable examples (which an agent matches against far faster than it parses a description):

$ hf models ls --help
...
Examples
...

명령어 트리(command tree)는 리소스 + 동사 (resource + verb) 구조로 일관적이며, 명확한 별칭(aliases)을 제공합니다 (hf models ls, hf repos create, hf jobs ps, hf collections delete; list/ls, remove/rm). 따라서 에이전트가 명령어 하나를 학습하면 나머지를 추측할 수 있습니다. 또한 출력 결과가 조합 가능합니다: -q는 다음 명령어로 파이프(pipe)할 수 있도록 한 줄에 하나의 ID를 출력하며, --json은 jq에 전달할 수 있는 형식을 제공합니다.

$ hf models ls --author Qwen -q | head -3
Qwen/Qwen3-0.6B
Qwen/Qwen2.5-1.5B-Instruct
...

hf CLI가 실제로 에이전트에게 더 효율적인지 알아보기 위해 직접 측정해 보았습니다. 저희는 작은 평가 하네스(evaluation harness)를 구축하고, Hub를 제어하는 각 방식에 대해 동일한 Hub 작업 세트를 여러 번 실행하며, 모든 실행 결과를 실제 Hub와 대조하여 채점했습니다. 방법론을 설명하기에 앞서 핵심 결과부터 말씀드리자면: 두 에이전트 모두에서 hf CLI가 앞서 나갔으며, 특히 복잡한 다단계 작업(multi-step tasks)에서 훨씬 적은 토큰을 사용하여 가장 명확한 차이를 보였습니다.

agent	tool	success score	token usage	self-report error
Claude Code (Sonnet 4.6)	hf CLI	0.94	baseline	2 / 163
	curl / Python SDK	0.84	1.3-1.6× tokens	11 / 163
Codex (GPT-5.5)	hf CLI	0.93	baseline	3 / 163
	curl / Python SDK	0.92	1.6-1.8× tokens	10 / 163

(self-report error = 에이전트는 17개의 해결 가능한 작업에 대해 성공했다고 보고했으나, Hub의 결과는 달랐던 경우. hf CLI 행은 해당 스킬이 설치된 CLI를 의미합니다. 이 스킬이 기본 CLI에 추가로 제공하는 이점(주로 더 적은 도구 호출)은 아래 스킬 섹션에서 별도로 다룹니다. 대표적인 트랜스크립트(transcripts)는 이 버킷에 공개되어 있습니다.)

우리는 **18개의 사소하지 않은 Hub 작업(non-trivial Hub tasks)**을 정의했습니다. 단순히 "파일 다운로드"와 같은 것이 아니라, 실제로 요청할 법한 작업들입니다. 예를 들어, 트렌딩 중인 조직(org)의 모델들을 집계하거나, 리포지토리(repo)의 파일과 그 크기를 검사하고, 포함/제외(include/exclude) 규칙이 적용된 폴더를 업로드하거나, 파일을 삭제하고, 리포지토리 간에 파일을 복사하며, 라이선스를 추가하는 PR(Pull Request)을 열고, 브랜치(branch)와 태그(tag)가 포함된 리포지토리를 생성하고, 버킷(bucket)을 동기화 및 정리(prune)하며, 컬렉션(collection)을 빌드하는 작업 등이 포함됩니다. 각 작업은 정확히 한 가지의 Hub 통신 방식만을 가진 새로운 코딩 에이전트(coding agent)에게 전달됩니다:

• hf CLI
• 또는 curl / Python SDK: hf CLI가 전혀 없는 환경으로, 에이전트는 REST API에 대한 curl 호출이나 huggingface_hub Python 라이브러리로 대체하여 수행합니다.

우리는 hf CLI를 스킬(skill, 별도 섹션에서 다시 다룰 생성된 명령 참조 기능)이 있는 경우와 없는 경우의 두 가지 설정으로 실행합니다. 하지만 아래의 핵심 비교는 단순히 hf CLI vs curl / SDK입니다. 스킬의 점진적인 효과는 메인 결과에 포함시키기에는 너무 작기 때문에 별도로 분리하여 다룹니다.

설정은 의도적으로 깔끔하게 유지했습니다. 실행당 새로운 인스턴스를 사용하며, 커스텀 MCP 서버, CLAUDE.md 또는 AGENTS.md, 그리고 행동을 유도할 수 있는 컨텍스트(context) 내의 그 어떤 것도 포함하지 않았습니다. 작업(task)과 도구(tool)는 단일 프롬프트(prompt)에 들어가며, 에이전트는 TASK_COMPLETE 또는 TASK_FAILED 마커로 작업을 마칩니다. 하지만 우리는 그 마커를 신뢰하지 않습니다(에이전트는 실제로 완료되지 않은 작업에 대해서도 성공했다고 보고할 수 있기 때문입니다). 따라서 우리는 **실제 Hub에 재질의(re-querying)**함으로써 모든 실행을 독립적으로 채점합니다. 즉, 브랜치가 실제로 생성되었는지, 파일이 실제로 삭제되었는지, 버킷이 존재하는지 등을 확인합니다. 코딩 에이전트는 비결정론적(non-deterministic)이므로 각 작업/도구 조합은 10회씩 실행되며, 에이전트당 약 520회 실행(18개 작업 × 3개 도구 × 10회 반복, 유료 Jobs 작업 1개에 대한 제한 제외)을 수행하여 총 약 1,000회의 채점된 실행을 완료했습니다. 우리는 가장 인기 있는 두 코딩 에이전트(Sonnet 4.6을 사용하는 Claude Code 및 GPT-5.5를 사용하는 OpenAI Codex)를 대상으로 이 전체 과정을 두 번 실시했습니다.

아래의 두 차트는 위의 표를 상세히 분석합니다. 첫 번째는 curl과 SDK가 가장 고전하는 에이전트인 Sonnet에서의 작업 성공률입니다:

CLI가 없다면 curl과 SDK는 10포인트 뒤처지게 되는데, 이는 Sonnet에서 이들이 작업의 일부(주로 쓰기 작업)를 단순히 완료하지 못하는 반면, hf CLI는 이를 해결하기 때문입니다.

두 번째 이미지는 작업별로 세분화된 **GPT-5.5에 미치는 토큰 영향 (token impact)**을 보여줍니다. 각 막대는 동일한 작업에 대해 curl/SDK의 토큰 수를 CLI의 토큰 수로 나눈 값입니다. 따라서 2.4×는 non-hf 버전이 동일한 일을 수행하기 위해 2.4배 더 많은 토큰을 소모했음을 의미합니다: