Hugging Face CLI

1---
2name: hugging-face-cli
3description: Execute Hugging Face Hub operations using the `hf` CLI. Use when the user needs to download models/datasets/spaces, upload files to Hub repositories, create repos, manage local cache, or run compute jobs on HF infrastructure. Covers authentication, file transfers, repository creation, cache operations, and cloud compute.
4---
5 
6# Hugging Face CLI
7 
8The `hf` CLI provides direct terminal access to the Hugging Face Hub for downloading, uploading, and managing repositories, cache, and compute resources.
9 
10## Quick Command Reference
11 
12| Task | Command |
13|------|---------|
14| Login | `hf auth login` |
15| Download model | `hf download <repo_id>` |
16| Download to folder | `hf download <repo_id> --local-dir ./path` |
17| Upload folder | `hf upload <repo_id> . .` |
18| Create repo | `hf repo create <name>` |
19| Create tag | `hf repo tag create <repo_id> <tag>` |
20| Delete files | `hf repo-files delete <repo_id> <files>` |
21| List cache | `hf cache ls` |
22| Remove from cache | `hf cache rm <repo_or_revision>` |
23| List models | `hf models ls` |
24| Get model info | `hf models info <model_id>` |
25| List datasets | `hf datasets ls` |
26| Get dataset info | `hf datasets info <dataset_id>` |
27| List spaces | `hf spaces ls` |
28| Get space info | `hf spaces info <space_id>` |
29| List endpoints | `hf endpoints ls` |
30| Run GPU job | `hf jobs run --flavor a10g-small <image> <cmd>` |
31| Environment info | `hf env` |
32 
33## Core Commands
34 
35### Authentication
36```bash
37hf auth login                    # Interactive login
38hf auth login --token $HF_TOKEN  # Non-interactive
39hf auth whoami                   # Check current user
40hf auth list                     # List stored tokens
41hf auth switch                   # Switch between tokens
42hf auth logout                   # Log out
43```
44 
45### Download
46```bash
47hf download <repo_id>                              # Full repo to cache
48hf download <repo_id> file.safetensors             # Specific file
49hf download <repo_id> --local-dir ./models         # To local directory
50hf download <repo_id> --include "*.safetensors"    # Filter by pattern
51hf download <repo_id> --repo-type dataset          # Dataset
52hf download <repo_id> --revision v1.0              # Specific version
53```
54 
55### Upload
56```bash
57hf upload <repo_id> . .                            # Current dir to root
58hf upload <repo_id> ./models /weights              # Folder to path
59hf upload <repo_id> model.safetensors              # Single file
60hf upload <repo_id> . . --repo-type dataset        # Dataset
61hf upload <repo_id> . . --create-pr                # Create PR
62hf upload <repo_id> . . --commit-message="msg"     # Custom message
63```
64 
65### Repository Management
66```bash
67hf repo create <name>                              # Create model repo
68hf repo create <name> --repo-type dataset          # Create dataset
69hf repo create <name> --private                    # Private repo
70hf repo create <name> --repo-type space --space_sdk gradio  # Gradio space
71hf repo delete <repo_id>                           # Delete repo
72hf repo move <from_id> <to_id>                     # Move repo to new namespace
73hf repo settings <repo_id> --private true          # Update repo settings
74hf repo list --repo-type model                     # List repos
75hf repo branch create <repo_id> release-v1         # Create branch
76hf repo branch delete <repo_id> release-v1         # Delete branch
77hf repo tag create <repo_id> v1.0                  # Create tag
78hf repo tag list <repo_id>                         # List tags
79hf repo tag delete <repo_id> v1.0                  # Delete tag
80```
81 
82### Delete Files from Repo
83```bash
84hf repo-files delete <repo_id> folder/             # Delete folder
85hf repo-files delete <repo_id> "*.txt"             # Delete with pattern
86```
87 
88### Cache Management
89```bash
90hf cache ls                      # List cached repos
91hf cache ls --revisions          # Include individual revisions
92hf cache rm model/gpt2           # Remove cached repo
93hf cache rm <revision_hash>      # Remove cached revision
94hf cache prune                   # Remove detached revisions
95hf cache verify gpt2             # Verify checksums from cache
96```
97 
98### Browse Hub
99```bash
100# Models
101hf models ls                                        # List top trending models
102hf models ls --search "MiniMax" --author MiniMaxAI  # Search models
103hf models ls --filter "text-generation" --limit 20  # Filter by task
104hf models info MiniMaxAI/MiniMax-M2.1               # Get model info
105 
106# Datasets
107hf datasets ls                                      # List top trending datasets
108hf datasets ls --search "finepdfs" --sort downloads # Search datasets
109hf datasets info HuggingFaceFW/finepdfs             # Get dataset info
110 
111# Spaces
112hf spaces ls                                        # List top trending spaces
113hf spaces ls --filter "3d" --limit 10               # Filter by 3D modeling spaces
114hf spaces info enzostvs/deepsite                    # Get space info
115```
116 
117### Jobs (Cloud Compute)
118```bash
119hf jobs run python:3.12 python script.py           # Run on CPU
120hf jobs run --flavor a10g-small <image> <cmd>      # Run on GPU
121hf jobs run --secrets HF_TOKEN <image> <cmd>       # With HF token
122hf jobs ps                                         # List jobs
123hf jobs logs <job_id>                              # View logs
124hf jobs cancel <job_id>                            # Cancel job
125```
126 
127### Inference Endpoints
128```bash
129hf endpoints ls                                     # List endpoints
130hf endpoints deploy my-endpoint \
131  --repo openai/gpt-oss-120b \
132  --framework vllm \
133  --accelerator gpu \
134  --instance-size x4 \
135  --instance-type nvidia-a10g \
136  --region us-east-1 \
137  --vendor aws
138hf endpoints describe my-endpoint                   # Show endpoint details
139hf endpoints pause my-endpoint                      # Pause endpoint
140hf endpoints resume my-endpoint                     # Resume endpoint
141hf endpoints scale-to-zero my-endpoint              # Scale to zero
142hf endpoints delete my-endpoint --yes               # Delete endpoint
143```
144**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`
145 
146## Common Patterns
147 
148### Download and Use Model Locally
149```bash
150# Download to local directory for deployment
151hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./model
152 
153# Or use cache and get path
154MODEL_PATH=$(hf download meta-llama/Llama-3.2-1B-Instruct --quiet)
155```
156 
157### Publish Model/Dataset
158```bash
159hf repo create my-username/my-model --private
160hf upload my-username/my-model ./output . --commit-message="Initial release"
161hf repo tag create my-username/my-model v1.0
162```
163 
164### Sync Space with Local
165```bash
166hf upload my-username/my-space . . --repo-type space \
167  --exclude="logs/*" --delete="*" --commit-message="Sync"
168```
169 
170### Check Cache Usage
171```bash
172hf cache ls                      # See all cached repos and sizes
173hf cache rm model/gpt2           # Remove a repo from cache
174```
175 
176## Key Options
177 
178- `--repo-type`: `model` (default), `dataset`, `space`
179- `--revision`: Branch, tag, or commit hash
180- `--token`: Override authentication
181- `--quiet`: Output only essential info (paths/URLs)
182 
183## References
184 
185- **Complete command reference**: See [references/commands.md](references/commands.md)
186- **Workflow examples**: See [references/examples.md](references/examples.md)
187