When to Use
Use this skill when you need to interact with the Hugging Face Hub via the hf CLI. This includes:
- Downloading, uploading, and managing models, datasets, and spaces.
- Handling authentication and managing local cache.
- Managing Hugging Face Buckets.
- Running or scheduling jobs on Hugging Face infrastructure.
- Deploying and managing Inference Endpoints.
- Interacting with collections, discussions, papers, and webhooks.
Prerequisites
- The
hf CLI must be installed.
- A Hugging Face account and Access Token (set as
HF_TOKEN environment variable or passed via --token).
- Windows host is primary (PowerShell). If using bash commands from external sources, ensure you have a compatible shell (e.g., Git Bash, WSL) or adapt them.
Procedure
1. Installation
Install the hf CLI by downloading the installer script, reviewing it, and running it locally.
PowerShell (Windows Host):
$tmpdir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()))
$installScript = Join-Path $tmpdir.FullName "hf-install.sh"
Invoke-WebRequest -Uri "https://hf.co/cli/install.sh" -OutFile $installScript
# Review the script before running
Get-Content $installScript
# Run the script (requires bash, e.g., via Git Bash or WSL)
bash $installScript
Remove-Item -Recurse -Force $tmpdir.FullName
Note: The hf command replaces the deprecated huggingface-cli command.
2. Authentication
Authenticate using a token from huggingface.co/settings/tokens.
# Recommended: Set HF_TOKEN environment variable
$env:HF_TOKEN = "YOUR_KEY"
# Or login via browser
hf auth login
# Verify login
hf auth whoami
3. Core Commands
Downloading and Uploading
- Download a model:
hf download openai-community/gpt2 --local-dir ./gpt2
- Upload a folder:
hf upload my-username/my-model ./local-folder --type model
- Upload large folder (resumable):
hf upload-large-folder my-username/my-model ./large-folder --type model
Managing Repositories
Jobs
Inference Endpoints
Cache Management
- List cache:
hf cache list
- Prune detached revisions:
hf cache prune --dry-run
4. Mounting Repos as Local Filesystems
Use hf-mount to mount Hub repositories or buckets as local filesystems.
PowerShell Installation:
$tmpdir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()))
$installScript = Join-Path $tmpdir.FullName "hf-mount-install.sh"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/huggingface/hf-mount/main/install.sh" -OutFile $installScript
# Review the script
Get-Content $installScript
# Run the script (requires bash)
sh $installScript
Remove-Item -Recurse -Force $tmpdir.FullName
Usage:
# Mount a repo (read-only)
hf-mount start repo openai-community/gpt2 ./gpt2-mount
# Mount a bucket (read-write)
hf-mount start --hf-token $env:HF_TOKEN bucket myuser/my-bucket ./data-mount
# Unmount
hf-mount stop ./data-mount
Pitfalls
- Deprecated CLI: The
huggingface-cli command is deprecated. Use hf instead. Auth commands are now under hf auth (e.g., hf auth whoami).
- Token Security: Do not hardcode tokens in scripts. Prefer setting the
HF_TOKEN environment variable.
- Large Uploads: For large folders, use
hf upload-large-folder instead of hf upload to ensure resumability.
- Shell Compatibility: The provided install scripts are bash scripts. On Windows, ensure you have Git Bash, WSL, or a similar environment to execute them, or use PowerShell equivalents as shown in the Procedure.
- Irreversible Actions:
hf repos delete and hf buckets delete are irreversible. Always double-check the target ID and use --dry-run where available.
- Scope Limitations: Use this skill only when the task clearly matches its upstream product or API scope. Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes. Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
Verification
Check CLI Version:
hf version
Expected output: Prints the current hf version (generated with huggingface_hub v1.21.0 or later).
Verify Authentication:
hf auth whoami
Expected output: Your Hugging Face username and account details.
List Cached Repositories:
hf cache list
Expected output: A list of locally cached repositories and revisions.
Check Environment:
hf env
Expected output: Information about the current environment, including token status and cache directory.
1---
2name: hugging-face-cli
3description: "Operates the Hugging Face Hub via the hf CLI (replaces huggingface-cli): download/upload models datasets spaces, auth, cache, buckets, jobs, inference endpoints, collections, papers, and webhooks. Use when the task is Hub file or repo operations from a terminal. Not for training loops, Gradio Space Python, or treating huggingface_hub Python as the primary interface."
4version: 1.0.1
5risk: unknown
6source: https://github.com/huggingface/skills/tree/main/skills/hf-cli
7source_repo: huggingface/skills
8source_type: official
9date_added: 2026-07-01
10license: Apache-2.0
11license_source: https://github.com/huggingface/skills/blob/main/LICENSE
12metadata:
13 source: https://skillmd.com/skills/kayforkind/hugging-face-cli
14---
15
16## When to Use
17
18Use this skill when you need to interact with the Hugging Face Hub via the `hf` CLI. This includes:
19- Downloading, uploading, and managing models, datasets, and spaces.
20- Handling authentication and managing local cache.
21- Managing Hugging Face Buckets.
22- Running or scheduling jobs on Hugging Face infrastructure.
23- Deploying and managing Inference Endpoints.
24- Interacting with collections, discussions, papers, and webhooks.
25
26## Prerequisites
27
28- The `hf` CLI must be installed.
29- A Hugging Face account and Access Token (set as `HF_TOKEN` environment variable or passed via `--token`).
30- Windows host is primary (PowerShell). If using bash commands from external sources, ensure you have a compatible shell (e.g., Git Bash, WSL) or adapt them.
31
32## Procedure
33
34### 1. Installation
35
36Install the `hf` CLI by downloading the installer script, reviewing it, and running it locally.
37
38**PowerShell (Windows Host)**:
39```powershell
40$tmpdir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()))
41$installScript = Join-Path $tmpdir.FullName "hf-install.sh"
42Invoke-WebRequest -Uri "https://hf.co/cli/install.sh" -OutFile $installScript
43# Review the script before running
44Get-Content $installScript
45# Run the script (requires bash, e.g., via Git Bash or WSL)
46bash $installScript
47Remove-Item -Recurse -Force $tmpdir.FullName
48```
49
50*Note: The `hf` command replaces the deprecated `huggingface-cli` command.*
51
52### 2. Authentication
53
54Authenticate using a token from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).
55
56```powershell
57# Recommended: Set HF_TOKEN environment variable
58$env:HF_TOKEN = "YOUR_KEY"
59
60# Or login via browser
61hf auth login
62
63# Verify login
64hf auth whoami
65```
66
67### 3. Core Commands
68
69#### Downloading and Uploading
70- **Download a model**:
71 ```powershell
72 hf download openai-community/gpt2 --local-dir ./gpt2
73 ```
74- **Upload a folder**:
75 ```powershell
76 hf upload my-username/my-model ./local-folder --type model
77 ```
78- **Upload large folder (resumable)**:
79 ```powershell
80 hf upload-large-folder my-username/my-model ./large-folder --type model
81 ```
82
83#### Managing Repositories
84- **List models**:
85 ```powershell
86 hf models list --search "gpt2" --limit 10
87 ```
88- **Create a new repo**:
89 ```powershell
90 hf repos create my-username/my-new-repo --type model --private
91 ```
92
93#### Jobs
94- **Run a job**:
95 ```powershell
96 hf jobs run ubuntu:latest "echo hello" --flavor cpu-basic
97 ```
98- **Schedule a job**:
99 ```powershell
100 hf jobs scheduled run "0 0 * * *" ubuntu:latest "echo daily" --flavor cpu-basic
101 ```
102
103#### Inference Endpoints
104- **Deploy from catalog**:
105 ```powershell
106 hf endpoints catalog deploy --repo openai-community/gpt2
107 ```
108
109#### Cache Management
110- **List cache**:
111 ```powershell
112 hf cache list
113 ```
114- **Prune detached revisions**:
115 ```powershell
116 hf cache prune --dry-run
117 ```
118
119### 4. Mounting Repos as Local Filesystems
120
121Use `hf-mount` to mount Hub repositories or buckets as local filesystems.
122
123**PowerShell Installation**:
124```powershell
125$tmpdir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()))
126$installScript = Join-Path $tmpdir.FullName "hf-mount-install.sh"
127Invoke-WebRequest -Uri "https://raw.githubusercontent.com/huggingface/hf-mount/main/install.sh" -OutFile $installScript
128# Review the script
129Get-Content $installScript
130# Run the script (requires bash)
131sh $installScript
132Remove-Item -Recurse -Force $tmpdir.FullName
133```
134
135**Usage**:
136```powershell
137# Mount a repo (read-only)
138hf-mount start repo openai-community/gpt2 ./gpt2-mount
139# Mount a bucket (read-write)
140hf-mount start --hf-token $env:HF_TOKEN bucket myuser/my-bucket ./data-mount
141# Unmount
142hf-mount stop ./data-mount
143```
144
145## Pitfalls
146
147- **Deprecated CLI**: The `huggingface-cli` command is deprecated. Use `hf` instead. Auth commands are now under `hf auth` (e.g., `hf auth whoami`).
148- **Token Security**: Do not hardcode tokens in scripts. Prefer setting the `HF_TOKEN` environment variable.
149- **Large Uploads**: For large folders, use `hf upload-large-folder` instead of `hf upload` to ensure resumability.
150- **Shell Compatibility**: The provided install scripts are bash scripts. On Windows, ensure you have Git Bash, WSL, or a similar environment to execute them, or use PowerShell equivalents as shown in the Procedure.
151- **Irreversible Actions**: `hf repos delete` and `hf buckets delete` are irreversible. Always double-check the target ID and use `--dry-run` where available.
152- **Scope Limitations**: Use this skill only when the task clearly matches its upstream product or API scope. Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes. Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
153
154## Verification
155
1561. **Check CLI Version**:
157 ```powershell
158 hf version
159 ```
160 *Expected output*: Prints the current `hf` version (generated with `huggingface_hub v1.21.0` or later).
161
1622. **Verify Authentication**:
163 ```powershell
164 hf auth whoami
165 ```
166 *Expected output*: Your Hugging Face username and account details.
167
1683. **List Cached Repositories**:
169 ```powershell
170 hf cache list
171 ```
172 *Expected output*: A list of locally cached repositories and revisions.
173
1744. **Check Environment**:
175 ```powershell
176 hf env
177 ```
178 *Expected output*: Information about the current environment, including token status and cache directory.