HuggingFace CLI 速查表
HuggingFace CLI 是与 HuggingFace Hub 交互的命令行工具。用于下载/上传模型和数据集、管理缓存、创建/删除仓库、身份认证等。下载大模型时支持断点续传和文件过滤，国内用户可配置镜像端点加速。
快速开始
``bash
# 登录
huggingface-cli login --token hf_xxxxxxxx
# 下载模型 huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models
# 只下载 GGUF 文件 huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF --include '*.gguf'
# 查看当前用户 huggingface-cli whoami
# 查看缓存
huggingface-cli scan-cache
`
身份认证
huggingface-cli login --token 登录。token 在 huggingface.co/settings/tokens 管理。CI/CD 用 export HF_TOKEN=hf_xxx。需要审核的模型（如 Llama）需要已同意的 token。
下载模型
download 是最常用的命令。关键参数：--local-dir（输出路径）、--include（文件过滤）、--exclude（排除文件）、--repo-type（仓库类型）、--revision（版本）、--resume-download（断点续传）。
上传文件
用 upload 推送文件。先 repo create 创建仓库再上传。支持 --repo-type 指定数据集仓库。大文件（>5MB）自动 LFS 管理。
缓存管理
scan-cache 查看缓存。delete-cache 交互式删除。export HF_HOME=/path 变更缓存位置。默认 ~/.cache/huggingface/hub 可能占用 100GB+ 空间。
环境变量
HF_TOKEN（认证）、HF_ENDPOINT（国内镜像 https://hf-mirror.com）、HF_HOME（缓存路径）、HF_HUB_ENABLE_HF_TRANSFER=1`（hf_transfer 加速下载）。
启动模式(14)
| 命令 | 难度 | ||
|---|---|---|---|
huggingface-cli --help显示 huggingface-cli 帮助 | 基础 | huggingface-cli --help | |
huggingface-cli login登录 HuggingFace 账号 | 基础 | huggingface-cli login --token hf_xxx | |
huggingface-cli logout退出登录 | 基础 | huggingface-cli logout | |
huggingface-cli whoami查看当前登录用户 | 基础 | huggingface-cli whoami | |
huggingface-cli scan-cache扫描 HuggingFace 缓存 | 中级 | huggingface-cli scan-cache | |
huggingface-cli delete-cache清理缓存中的指定版本 | 中级 | huggingface-cli delete-cache | |
huggingface-cli env显示 HuggingFace 环境信息 | 基础 | huggingface-cli env | |
huggingface-cli repo create创建一个新仓库 | 中级 | huggingface-cli repo create my-new-model --type model | |
huggingface-cli repo delete删除一个仓库 | 高级 | huggingface-cli repo delete my-user/old-model | |
huggingface-cli lfs-enable-largefiles启用大文件支持（LFS） | 中级 | huggingface-cli lfs-enable-largefiles ./repo | |
huggingface-cli tag为仓库版本打标签 | 中级 | huggingface-cli tag my-user/my-model v1.0 | |
huggingface-cli list列出已登录用户的模型/数据集 | 基础 | huggingface-cli list | |
export HF_TOKEN设置 HuggingFace Token 环境变量 | 基础 | export HF_TOKEN=hf_xxxxxxxxxxxx | |
export HF_ENDPOINT设置 HuggingFace 镜像端点（国内用户） | 基础 | export HF_ENDPOINT=https://hf-mirror.com |
ai-model(10)
| 命令 | 难度 | ||
|---|---|---|---|
huggingface-cli download下载模型或数据集（核心功能） | 基础 | huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models/llama | |
huggingface-cli download --local-dir指定下载到本地目录 | 基础 | huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models | |
huggingface-cli download --repo-type指定仓库类型（model/dataset/space） | 中级 | huggingface-cli download databricks/databricks-dolly-15k --repo-type dataset | |
huggingface-cli download --revision下载指定版本/分支 | 中级 | huggingface-cli download meta-llama/Llama-3.1-8B --revision main | |
huggingface-cli download --include只下载匹配模式的文件 | 中级 | huggingface-cli download meta-llama/Llama-3.1-8B --include '*.gguf' | |
huggingface-cli download --exclude排除匹配模式的文件 | 中级 | huggingface-cli download meta-llama/Llama-3.1-8B --exclude '*.safetensors' | |
huggingface-cli download --cache-dir指定缓存目录 | 中级 | huggingface-cli download meta-llama/Llama-3.1-8B --cache-dir /data/hf-cache | |
huggingface-cli upload上传文件到 HuggingFace | 中级 | huggingface-cli upload my-user/my-model ./model.gguf | |
huggingface-cli upload --repo-type上传到指定类型仓库 | 中级 | huggingface-cli upload my-user/my-dataset ./data --repo-type dataset | |
huggingface-cli download --resume-download断点续传下载 | 中级 | huggingface-cli download meta-llama/Llama-3.1-8B --resume-download |