토큰, 접근 권한, CLI 로그인

토큰에는 맡은 일만 허용해

HF 사용자 토큰은 read, write, fine-grained 권한을 제공해. read면 공개 모델 다운로드, 제한 모델의 라이선스 동의, Inference API 호출에 충분해. write는 저장소 생성·푸시·삭제까지 허용하지. 서비스와 CI에는 특정 조직이나 저장소만 허용하는 fine-grained 토큰이 기본 선택이야.

클라이언트가 토큰을 찾는 순서

huggingface-cli login으로 로그인하면 토큰은 기본적으로 ~/.cache/huggingface/token에 저장돼. 위치는 HF_HOME으로 바꿀 수 있고, Transformers·Datasets·huggingface_hub·Accelerate가 이 값을 함께 사용해. Docker나 CI에서는 HF_TOKEN 환경 변수로 해당 프로세스에만 주입하는 방식이 표준이야.

회전은 사고가 난 뒤에 하는 일이 아니야

토큰 설정 화면에는 생성 시각과 마지막 사용 시각이 표시돼. CI 러너에서 90일 넘게 쓴 토큰은 교체하고, 더 이상 쓰지 않는 토큰은 폐기해. read 토큰이 새면 피해 범위가 제한적이지만 write 토큰 유출은 저장소 변조로 이어질 수 있어. 즉시 회전하고 푸시 이력을 감사하며 비밀값 탐지와 푸시 보호도 함께 켜.

Code

# Interactive — 가장 흔함
huggingface-cli login

# Non-interactive (CI)
echo "${HF_TOKEN}" | huggingface-cli login --token "${HF_TOKEN}" --add-to-git-credential

# whoami 로 확인
huggingface-cli whoami

# 토큰 파일 위치 (디폴트)
ls -l ~/.cache/huggingface/token

토큰 override priority·python

import os
from huggingface_hub import HfApi

# 우선순위: explicit token 인자 > HF_TOKEN env > ~/.cache/huggingface/token

# Explicit (가장 높음 — token kwarg 받는 라이브러리에서 씀)
api = HfApi(token=os.environ.get("HF_PROD_TOKEN"))
print(api.whoami())

# Implicit (env 또는 cache)
api2 = HfApi()
print(api2.whoami())

Exercise

공개 저장소 읽기만 허용한 fine-grained 토큰 하나와, 새 테스트 저장소({your-username}/scratch-{date})에만 쓰기를 허용한 토큰 하나를 만들어. 둘 다 whoami로 확인하고 .env에 저장해. 쓰기 토큰으로 README.md를 푸시한 뒤 읽기 토큰으로 같은 작업을 시도해 권한 오류를 확인해.