Hugging Face CLI

The hf CLI provides direct terminal access to the Hugging Face Hub for downloading, uploading, and managing repositories, cache, and compute resources.

Quick Command Reference

Task Command

Login hf auth login

Download model hf download <repo_id>

Download to folder hf download <repo_id> --local-dir ./path

Upload folder hf upload <repo_id> . .

Create repo hf repo create <name>

Create tag hf repo tag create <repo_id> <tag>

Delete files hf repo-files delete <repo_id> <files>

List cache hf cache ls

Remove from cache hf cache rm <repo_or_revision>

List models hf models ls

Get model info hf models info <model_id>

List datasets hf datasets ls

Get dataset info hf datasets info <dataset_id>

List spaces hf spaces ls

Get space info hf spaces info <space_id>

List endpoints hf endpoints ls

Run GPU job hf jobs run --flavor a10g-small <image> <cmd>

Environment info hf env

Core Commands

Authentication

hf auth login # Interactive login hf auth login --token $HF_TOKEN # Non-interactive hf auth whoami # Check current user hf auth list # List stored tokens hf auth switch # Switch between tokens hf auth logout # Log out

Download

hf download <repo_id> # Full repo to cache hf download <repo_id> file.safetensors # Specific file hf download <repo_id> --local-dir ./models # To local directory hf download <repo_id> --include "*.safetensors" # Filter by pattern hf download <repo_id> --repo-type dataset # Dataset hf download <repo_id> --revision v1.0 # Specific version

Upload

hf upload <repo_id> . . # Current dir to root hf upload <repo_id> ./models /weights # Folder to path hf upload <repo_id> model.safetensors # Single file hf upload <repo_id> . . --repo-type dataset # Dataset hf upload <repo_id> . . --create-pr # Create PR hf upload <repo_id> . . --commit-message="msg" # Custom message

Repository Management

hf repo create <name> # Create model repo hf repo create <name> --repo-type dataset # Create dataset hf repo create <name> --private # Private repo hf repo create <name> --repo-type space --space_sdk gradio # Gradio space hf repo delete <repo_id> # Delete repo hf repo move <from_id> <to_id> # Move repo to new namespace hf repo settings <repo_id> --private true # Update repo settings hf repo list --repo-type model # List repos hf repo branch create <repo_id> release-v1 # Create branch hf repo branch delete <repo_id> release-v1 # Delete branch hf repo tag create <repo_id> v1.0 # Create tag hf repo tag list <repo_id> # List tags hf repo tag delete <repo_id> v1.0 # Delete tag

Delete Files from Repo

hf repo-files delete <repo_id> folder/ # Delete folder hf repo-files delete <repo_id> "*.txt" # Delete with pattern

Cache Management

hf cache ls # List cached repos hf cache ls --revisions # Include individual revisions hf cache rm model/gpt2 # Remove cached repo hf cache rm <revision_hash> # Remove cached revision hf cache prune # Remove detached revisions hf cache verify gpt2 # Verify checksums from cache

Browse Hub

Models

hf models ls # List top trending models hf models ls --search "MiniMax" --author MiniMaxAI # Search models hf models ls --filter "text-generation" --limit 20 # Filter by task hf models info MiniMaxAI/MiniMax-M2.1 # Get model info

Datasets

hf datasets ls # List top trending datasets hf datasets ls --search "finepdfs" --sort downloads # Search datasets hf datasets info HuggingFaceFW/finepdfs # Get dataset info

Spaces

hf spaces ls # List top trending spaces hf spaces ls --filter "3d" --limit 10 # Filter by 3D modeling spaces hf spaces info enzostvs/deepsite # Get space info

Jobs (Cloud Compute)

hf jobs run python:3.12 python script.py # Run on CPU hf jobs run --flavor a10g-small <image> <cmd> # Run on GPU hf jobs run --secrets HF_TOKEN <image> <cmd> # With HF token hf jobs ps # List jobs hf jobs logs <job_id> # View logs hf jobs cancel <job_id> # Cancel job

Inference Endpoints

hf endpoints ls # List endpoints hf endpoints deploy my-endpoint
--repo openai/gpt-oss-120b
--framework vllm
--accelerator gpu
--instance-size x4
--instance-type nvidia-a10g
--region us-east-1
--vendor aws hf endpoints describe my-endpoint # Show endpoint details hf endpoints pause my-endpoint # Pause endpoint hf endpoints resume my-endpoint # Resume endpoint hf endpoints scale-to-zero my-endpoint # Scale to zero hf endpoints delete my-endpoint --yes # Delete endpoint

GPU Flavors: cpu-basic , cpu-upgrade , cpu-xl , t4-small , t4-medium , l4x1 , l4x4 , l40sx1 , l40sx4 , l40sx8 , a10g-small , a10g-large , a10g-largex2 , a10g-largex4 , a100-large , h100 , h100x8

Common Patterns

Download and Use Model Locally

Download to local directory for deployment

hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./model

Or use cache and get path

MODEL_PATH=$(hf download meta-llama/Llama-3.2-1B-Instruct --quiet)

Publish Model/Dataset

hf repo create my-username/my-model --private hf upload my-username/my-model ./output . --commit-message="Initial release" hf repo tag create my-username/my-model v1.0

Sync Space with Local

hf upload my-username/my-space . . --repo-type space
--exclude="logs/" --delete="" --commit-message="Sync"

Check Cache Usage

hf cache ls # See all cached repos and sizes hf cache rm model/gpt2 # Remove a repo from cache

Key Options

• --repo-type : model (default), dataset , space

• --revision : Branch, tag, or commit hash

• --token : Override authentication

• --quiet : Output only essential info (paths/URLs)

References

• Complete command reference: See references/commands.md

• Workflow examples: See references/examples.md