Hugging Face Skill#

This skill exposes the full Hugging Face Hub surface — both the huggingface-cli command-line tool and the huggingface_hub Python library — to every assistant interaction. It reads HF_TOKEN from the environment for authenticated operations; public read-only operations work without a token.

Token scope: HF_TOKEN is only required for private/gated model downloads, any upload, repo creation/deletion, and Space management. All public model/dataset browsing and downloads work without one.

---

Security Notice#

• Set HF_TOKEN in your shell environment or .env file — never hard-code it in scripts.
• Use fine-grained tokens (read-only or repo-scoped) over full write tokens where possible. Create them at https://huggingface.co/settings/tokens
• Gated models (Llama, Gemma, etc.) require both a token and accepted model terms on the Hub web UI.
• HF_HUB_OFFLINE=1 prevents all network calls — safe for air-gapped or CI environments where the cache is pre-populated.

---

Installation#

Minimum install#

bash

pip install huggingface_hub

Recommended install with all extras#

bash

pip install "huggingface_hub[cli,torch,tensorflow,fastai,dev]"

ExtraAddscli``huggingface-cli commandhf_transferFast Rust-based multi-part downloads ( pip install hf_transfer)torchPyTorch model helperstensorflowTF model helpersfastaifastai helpers

Enable fast downloads (optional)#

bash

pip install hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1

Verify install#

bash

huggingface-cli version
huggingface-cli whoami       # requires HF_TOKEN

---

Authentication#

Login (writes token to ~/.cache/huggingface/token)#

bash

huggingface-cli login
# or non-interactively:
huggingface-cli login --token $HF_TOKEN

Logout#

bash

huggingface-cli logout

Check current identity#

bash

huggingface-cli whoami

Environment variable (preferred for CI/scripts)#

bash

export HF_TOKEN=hf_...

The library reads HF_TOKEN automatically — no explicit login needed when this var is set.

---

Downloading Models and Datasets#

Download an entire model repo#

bash

huggingface-cli download <org/model>
# Example:
huggingface-cli download google/gemma-2b

Download a single file#

bash

huggingface-cli download <org/model> <filename>
huggingface-cli download openai/whisper-large-v3 config.json

Download to a specific directory#

bash

huggingface-cli download <org/model> --local-dir ./models/mymodel

Download a dataset repo#

bash

huggingface-cli download <org/dataset> --repo-type dataset

Download a specific revision (branch, tag, or commit SHA)#

bash

huggingface-cli download <org/model> --revision v1.0
huggingface-cli download <org/model> --revision abc1234

Download specific file patterns (glob)#

bash

huggingface-cli download <org/model> --include "*.safetensors"
huggingface-cli download <org/model> --exclude "*.bin" --include "*.safetensors"

Download gated model (requires token + accepted terms)#

bash

HF_TOKEN=hf_... huggingface-cli download meta-llama/Llama-3-8B

---

Uploading to the Hub#

Upload a single file#

bash

huggingface-cli upload <org/repo> <local_file> <path_in_repo>
huggingface-cli upload myorg/mymodel weights.safetensors model/weights.safetensors

Upload an entire folder#

bash

huggingface-cli upload <org/repo> <local_folder> <path_in_repo>
huggingface-cli upload myorg/mymodel ./model_dir .

Upload to a dataset repo#

bash

huggingface-cli upload myorg/mydataset ./data . --repo-type dataset

Upload to a Space#

bash

huggingface-cli upload myorg/myspace ./app . --repo-type space

Upload with commit message#

bash

huggingface-cli upload myorg/mymodel ./weights . --commit-message "Add fp16 weights"

Upload large folder (multi-part, resumable)#

bash

huggingface-cli upload-large-folder myorg/mymodel --repo-type model ./large_model_dir

---

Repository Management#

Create a repo#

bash

huggingface-cli repo create <repo-name>
huggingface-cli repo create my-model --type model
huggingface-cli repo create my-dataset --type dataset
huggingface-cli repo create my-space --type space

Delete a repo#

bash

huggingface-cli repo delete <org/repo>

Get repo info#

bash

huggingface-cli repo info <org/repo>
huggingface-cli repo info google/gemma-2b

---

Tags#

bash

huggingface-cli tag create  <org/repo> <tag>      --message "Release v1.0"
huggingface-cli tag list    <org/repo>
huggingface-cli tag delete  <org/repo> <tag>

---

Cache Management#

Scan cache (see what's stored locally)#

bash

huggingface-cli scan-cache

Delete unused cache entries interactively#

bash

huggingface-cli delete-cache

Show cache size summary#

bash

huggingface-cli scan-cache --verbose

---

Python API — Quick Patterns#

See templates/python_patterns.txt for full copy-paste code. Core entry point:

python

import os
from huggingface_hub import HfApi

api = HfApi(token=os.environ.get("HF_TOKEN"))

Use scripts/hf_helper.py as a CLI wrapper over the Python API for search, info, and cache operations without a browser.

---

Environment Variables#

VariableDefaultDescriptionHF_TOKEN—Access token; required for private/gated/write operationsHF_HOME``~/.cache/huggingfaceRoot cache directoryHF_HUB_CACHE``$HF_HOME/hubModel/dataset cacheHF_DATASETS_CACHE``$HF_HOME/datasetsDatasets library cacheHF_HUB_OFFLINE``0Set 1 to disable all network callsHF_HUB_ENABLE_HF_TRANSFER``0Set 1 to enable fast Rust downloaderHF_ENDPOINT``https://huggingface.coOverride for enterprise/mirror deploymentsHF_HUB_DISABLE_PROGRESS_BARS``0Set 1 to suppress tqdm bars (good for CI logs)HF_HUB_VERBOSITY``warningLog level: debug, info, warning, error``HUGGINGFACE_HUB_VERBOSITY—Legacy alias for HF_HUB_VERBOSITY

---

Best Practices#

1. Prefer --local-dir over default cache for reproducible paths#

The default cache uses content-addressed symlinks. Use --local-dir ./models/name when you need a stable, self-contained directory for an application.

2. Pin revisions in production#

Always pass --revision <commit-sha> in production downloads. Branches like main are mutable and can silently update between runs.

3. Use --include/ --exclude to skip unnecessary weights#

Large models ship both .bin and .safetensors formats. Download only what your framework uses:

bash

huggingface-cli download <model> --include "*.safetensors" --exclude "*.bin"

4. Pre-populate cache before going offline#

bash

huggingface-cli download <model>        # fills cache
export HF_HUB_OFFLINE=1                 # subsequent loads use cache only

5. Use fine-grained tokens with minimal scope#

Create per-project tokens at https://huggingface.co/settings/tokens — read-only tokens cannot accidentally delete or overwrite repos.

6. Commit model cards alongside weights#

Every upload is a git commit. Include a README.md (model card) in the upload folder so the repo is immediately browseable on the Hub.

7. Use upload-large-folder for models over ~50 GB#

upload-large-folder uses multi-part upload with automatic retry and deduplication — far more reliable than upload for very large checkpoints.

---

Troubleshooting#

SymptomFix401 UnauthorizedSet HF_TOKEN or run huggingface-cli login``403 Forbidden on gated modelAccept model terms on huggingface.co, then retryhuggingface-cli: command not found``pip install "huggingface_hub[cli]" and ensure pip bin is on PATHSlow downloadspip install hf_transfer and set HF_HUB_ENABLE_HF_TRANSFER=1``OSError: [Errno 28] No space leftRun huggingface-cli delete-cache to free cache spaceDownload resumes from wrong offsetUse --local-dir — the default cache can have stale partial blobsRepositoryNotFoundErrorCheck repo name spelling and that your token has accessRevisionNotFoundErrorVerify the branch/tag/SHA exists on the HubEntryNotFoundErrorFile not in this revision; check huggingface-cli repo infoEnterprise behind firewallSet HF_ENDPOINT=https://your-mirror.internal