허깅페이스, 코딩 에이전트용으로 hf CLI 재설계해 토큰 최대 6배 절감

허깅페이스가 허브를 다루는 공식 명령줄 도구 'hf CLI'를 사람과 AI 코딩 에이전트 양쪽 모두에 맞게 새로 설계했다고 밝혔다. hf는 모델·데이터셋·스페이스의 다운로드와 업로드, 저장소·브랜치·태그·풀리퀘스트 관리, 허깅페이스 인프라에서의 작업(Job) 실행 등 파이썬 SDK로 할 수 있는 일을 터미널에서 그대로 수행하는 도구다.

회사는 hf CLI가 오랫동안 일반 사용자를 위해 만들어졌지만 최근 들어 클로드 코드, 코덱스, 커서 같은 코딩 에이전트가 점점 더 많이 사용하게 됐다고 설명했다. 그래서 두 사용자층을 동시에 만족시키도록 도구를 다시 만들었다는 것이다.

핵심 성과는 토큰 절감이다. 허깅페이스의 자체 벤치마크에 따르면, 복잡한 다단계 작업에서 CLI 없이 에이전트가 curl이나 파이썬 SDK를 직접 다루는 방식은 hf CLI를 쓸 때보다 최대 6배 많은 토큰을 소비했다.

허깅페이스는 2026년 4월부터 허브에 대한 에이전트 사용량을 추적하기 시작했다. hf CLI와 그 기반인 huggingface_hub 파이썬 SDK는 에이전트가 설정하는 환경 변수를 읽어 코딩 에이전트가 명령을 실행 중인지 감지한다. 클로드 코드는 CLAUDECODE와 CLAUDE_CODE, 코덱스는 CODEX_SANDBOX를 쓰며 커서·제미나이·파이, 그리고 범용 AI_AGENT 변수도 인식한다.

이 신호는 두 가지 역할을 한다. 출력 형식을 바꾸는 동시에, 각 허브 요청에 'agent/<이름>' 형태의 사용자 에이전트 태그를 붙여 어떤 에이전트가 트래픽을 발생시켰는지 식별한다. 사용자 수 기준으로 가장 큰 둘은 클로드 코드와 코덱스로 나머지를 크게 앞섰다. 클로드 코드만 약 4만 명의 사용자와 거의 4,900만 건의 요청을 기록했고 코덱스가 바로 뒤를 이었다.

같은 명령이라도 사람과 에이전트는 다른 출력을 원한다. 사람은 색상과 정렬된 표, 화면에 맞게 잘린 결과, 성공 표시 등 풍부한 터미널 출력을 선호한다. 반면 에이전트는 색상 코드가 없고 아무것도 잘리지 않으며 모든 값이 온전히 담기되 토큰을 적게 쓰도록 압축되고 구조화된 출력을 원한다. hf는 v1.9.0에서 에이전트 모드 출력을 처음 도입한 뒤 이후 릴리스에서 점진적으로 확대해 왔다.

hf는 에이전트 사용을 자동으로 감지해 같은 명령을 다르게 보여준다. 사람에게는 정렬된 표와 더 자세히 보는 방법 안내를 제공하고, 에이전트에게는 전체 저장소 ID와 ISO 타임스탬프, 모든 태그를 담은 TSV를 색상 코드 없이 그대로 전달한다. 사용자는 --format 옵션으로 human, agent, json, quiet 형식을 직접 지정할 수도 있다.

명령을 실행한 뒤 다음에 쓸 명령을 미리 채워 알려주는 힌트 기능도 더해졌다. 작업을 백그라운드로 시작하면 로그 확인 명령을, 스페이스를 만들면 부팅 상태 확인 명령을 짚어준다. 힌트와 경고, 오류는 표준 에러로 보내고 데이터는 표준 출력으로 보내, 에이전트가 파싱하는 결과가 오염되지 않도록 했다.

에이전트가 누를 수 없는 대화형 입력 대기를 없앤 점도 특징이다. 삭제 같은 위험한 명령은 사람에게는 확인을 요구하지만 에이전트 모드에서는 즉시 실패하며 '--yes를 쓰라'는 해결책을 함께 알려준다. 또 저장소 생성 시 --exist-ok는 이미 있으면 아무 동작도 하지 않고, 데이터를 옮기는 명령은 --dry-run으로 실제 전송 전에 무엇을 옮길지 미리 보여줘 재시도에도 안전하도록 설계됐다.