HuggingFace CLI Cheatsheet

Q: How do I authenticate the HuggingFace CLI?

Run `huggingface-cli login --token hf_xxx`. Get your token from https://huggingface.co/settings/tokens. You can also set `export HF_TOKEN=hf_xxx` for non-interactive environments. Some models (like Llama) require approved access.

Q: How do I download a model to a specific directory?

Use `huggingface-cli download repo-id --local-dir ./my-models`. Add `--include '*.gguf'` to download only GGUF files. Add `--exclude '*.safetensors'` to skip certain formats. Use `--resume-download` for interrupted downloads.

Q: How do Chinese users speed up downloads?

Set `export HF_ENDPOINT=https://hf-mirror.com` to use the HuggingFace mirror. This dramatically increases download speeds from mainland China. You can also use `hf_transfer` for faster downloads: `pip install hf_transfer` and set `HF_HUB_ENABLE_HF_TRANSFER=1`.

Q: How do I upload my own model?

First create a repo: `huggingface-cli repo create my-model --type model`. Then upload: `huggingface-cli upload my-user/my-model ./model.gguf`. For large files, enable LFS first: `huggingface-cli lfs-enable-largefiles .`.

Q: How do I manage disk space used by HuggingFace cache?

Run `huggingface-cli scan-cache` to see what's cached. Then `huggingface-cli delete-cache` to remove unused versions. The cache lives at ~/.cache/huggingface/hub by default. You can change it with `export HF_HOME=/path/to/cache`.

The HuggingFace CLI is the command-line tool for interacting with the HuggingFace Hub. Use it to download/upload models and datasets, manage cache, create/delete repositories, and handle authentication. Supports resume downloads and file filtering for large model downloads.

Updated: 2026-07-20·24 commands

Quick Start

``bash # Login huggingface-cli login --token hf_xxxxxxxx

# Download a model huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models

# Download only GGUF files huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF --include '*.gguf'

# Check current user huggingface-cli whoami

# View cache usage huggingface-cli scan-cache`

`Authentication`

Login with huggingface-cli login --token . Tokens are managed at huggingface.co/settings/tokens. For CI/CD, use export HF_TOKEN=hf_xxx. Models requiring access approval (like Llama) need a token with accepted terms.

`Download`

The download command is the most used feature. Key flags: --local-dir (output path), --include (file filter), --exclude (skip files), --repo-type (model/dataset/space), --revision (branch/tag), --resume-download (resume interrupted), --cache-dir (custom cache).

`Upload`

Use upload to push files. First create a repo with repo create, then upload files. Supports --repo-type for dataset repos. For large files (>5MB), LFS is handled automatically.

`Cache Management`

scan-cache shows cached repos and versions. delete-cache interactively removes unused versions. Set HF_HOME to change the cache location. The default cache at ~/.cache/huggingface/hub can grow very large (100GB+ for multiple models).

`Environment Variables`

HF_TOKEN for authentication, HF_ENDPOINT for mirror endpoints (China: https://hf-mirror.com), HF_HOME for cache directory, HF_HUB_ENABLE_HF_TRANSFER=1 for faster downloads with hf_transfer`.

Startup & Modes(14)

Command	Level	Example
`huggingface-cli --help` Show huggingface-cli help	Basic	`huggingface-cli --help`
`huggingface-cli login` Log in to HuggingFace account	Basic	`huggingface-cli login --token hf_xxx`
`huggingface-cli logout` Log out	Basic	`huggingface-cli logout`
`huggingface-cli whoami` Check current logged-in user	Basic	`huggingface-cli whoami`
`huggingface-cli scan-cache` Scan HuggingFace cache	Intermediate	`huggingface-cli scan-cache`
`huggingface-cli delete-cache` Delete specific version from cache	Intermediate	`huggingface-cli delete-cache`
`huggingface-cli env` Show HuggingFace environment info	Basic	`huggingface-cli env`
`huggingface-cli repo create` Create a new repository	Intermediate	`huggingface-cli repo create my-new-model --type model`
`huggingface-cli repo delete` Delete a repository	Expert	`huggingface-cli repo delete my-user/old-model`
`huggingface-cli lfs-enable-largefiles` Enable large file support (LFS)	Intermediate	`huggingface-cli lfs-enable-largefiles ./repo`
`huggingface-cli tag` Tag a repository version	Intermediate	`huggingface-cli tag my-user/my-model v1.0`
`huggingface-cli list` List user's models/datasets	Basic	`huggingface-cli list`
`export HF_TOKEN` Set HuggingFace token environment variable	Basic	`export HF_TOKEN=hf_xxxxxxxxxxxx`
`export HF_ENDPOINT` Set HF mirror endpoint (for China users)	Basic	`export HF_ENDPOINT=https://hf-mirror.com`

ai-model(10)

Command	Level	Example
`huggingface-cli download` Download model or dataset (core feature)	Basic	`huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models/llama`
`huggingface-cli download --local-dir` Specify local download directory	Basic	`huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./models`
`huggingface-cli download --repo-type` Specify repo type (model/dataset/space)	Intermediate	`huggingface-cli download databricks/databricks-dolly-15k --repo-type dataset`
`huggingface-cli download --revision` Download specific version/branch	Intermediate	`huggingface-cli download meta-llama/Llama-3.1-8B --revision main`
`huggingface-cli download --include` Only download files matching pattern	Intermediate	`huggingface-cli download meta-llama/Llama-3.1-8B --include '*.gguf'`
`huggingface-cli download --exclude` Exclude files matching pattern	Intermediate	`huggingface-cli download meta-llama/Llama-3.1-8B --exclude '*.safetensors'`
`huggingface-cli download --cache-dir` Specify cache directory	Intermediate	`huggingface-cli download meta-llama/Llama-3.1-8B --cache-dir /data/hf-cache`
`huggingface-cli upload` Upload file to HuggingFace	Intermediate	`huggingface-cli upload my-user/my-model ./model.gguf`
`huggingface-cli upload --repo-type` Upload to specific repo type	Intermediate	`huggingface-cli upload my-user/my-dataset ./data --repo-type dataset`
`huggingface-cli download --resume-download` Resume interrupted download	Intermediate	`huggingface-cli download meta-llama/Llama-3.1-8B --resume-download`

FAQ

How do I authenticate the HuggingFace CLI?

How do I download a model to a specific directory?

How do Chinese users speed up downloads?

How do I upload my own model?

How do I manage disk space used by HuggingFace cache?

This cheatsheet is compiled from official tool documentation. Last updated: 2026-07-20.