$devvkit learn --librarie hugging-face-cli-guide

Hugging Face CLI Guide

[ai][models][datasets][hub]

AI / LLM Tools

Install

pip install huggingface-hub
# or: uv add huggingface-hub
# Login:
huggingface-cli login --token hf_...

The Hugging Face Hub hosts 1M+ models, datasets, and Spaces. The CLI lets you download models (`huggingface-cli download`), upload repos, query the Hub API, and manage Git-based model repositories without ever opening a browser.

Downloads use the `hf_transfer` Rust backend for multi-Gbps speeds. Download specific files: `--include "*.safetensors"` or `--exclude "*.bin"`. Use `--local-dir-use-symlinks False` for Docker environments (avoid symlink issues).

You can query the Hub API programmatically: `huggingface-cli list-models` filters by task, library, or license. The CLI also manages Spaces — deploy demos with `--space-sdk gradio`. For bulk operations, use the `huggingface_hub` Python library directly.

Login & Auth

huggingface-cli login                        # Interactive
huggingface-cli login --token hf_xxxxxxxxx    # Token from settings
huggingface-cli whoami                        # Verify login

# Environment variable:
export HF_TOKEN=hf_xxxxxxxxx
# Or in code:
from huggingface_hub import login; login()

Spaces deployment— Deploy ML demos.

huggingface-cli create-repo my-space --type space --space-sdk gradio
huggingface-cli upload my-space app.py requirements.txt \
  --repo-type space

# Update Space secrets:
huggingface-cli update-space-variable my-space --key HF_TOKEN --value hf_xxx

# Pause/restart Space:
huggingface-cli pause-space my-space
huggingface-cli restart-space my-space

Download Models

Download model— Download model files.

huggingface-cli download meta-llama/Llama-3.2-3B
huggingface-cli download meta-llama/Llama-3.2-3B --local-dir ./llama

# Download only GGUF:
huggingface-cli download TheBloke/Llama-2-7B-GGUF \
  --include "*.gguf" --local-dir ./models

# With progress and resume:
huggingface-cli download bigscience/bloom-560m \
  --resume-download --local-dir ./bloom

Python API— Programmatic downloads.

from huggingface_hub import hf_hub_download, snapshot_download

# Download single file:
hf_hub_download(
    repo_id='meta-llama/Llama-3.2-3B',
    filename='config.json',
    local_dir='./models'
)

# Download entire repo with filters:
snapshot_download(
    repo_id='TheBloke/Mistral-7B-GGUF',
    allow_patterns='*Q4_K_M*',
    local_dir='./mistral'
)

Upload

Upload files— Push to Hub.

huggingface-cli upload my-org/my-model ./checkpoints \
  --repo-type model

huggingface-cli upload my-repo ./data.csv \
  --commit-message "Add training data" \
  --repo-type dataset

# Create new repo:
huggingface-cli create-repo my-new-model --type model
huggingface-cli create-repo my-dataset --type dataset --private

Query Hub

List models— Search/filter models.

huggingface-cli list-models --task text-generation --limit 10
huggingface-cli list-models --library transformers --sort downloads
huggingface-cli list-models --search "code llama" --limit 5

# With license filter:
huggingface-cli list-models --license llama2,mit

List local cache— Manage cached files.

huggingface-cli scan-cache          # Show all cached models
huggingface-cli delete-cache        # Interactive clean-up
huggingface-cli env                 # Show env info and cache dir

# Environment variables:
export HF_HOME=/mnt/bigdisk/hf     # Change cache dir
export HF_HUB_DISABLE_SYMLINKS=1   # Docker-safe downloads

Datasets

Download dataset— Download dataset files.

huggingface-cli download --repo-type dataset \
  openslr/librispeech_asr --local-dir ./librispeech

huggingface-cli download --repo-type dataset \
  codeparrot/github-code --include "*.jsonl" \
  --local-dir ./github-code