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-cli3description: 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.4license: Apache-2.05---6
7## When to Use
8
9Use this skill when you need to interact with the Hugging Face Hub via the `hf` CLI. This includes:
10- Downloading, uploading, and managing models, datasets, and spaces.
11- Handling authentication and managing local cache.
12- Managing Hugging Face Buckets.
13- Running or scheduling jobs on Hugging Face infrastructure.
14- Deploying and managing Inference Endpoints.
15- Interacting with collections, discussions, papers, and webhooks.
16
17## Prerequisites
18
19- The `hf` CLI must be installed.
20- A Hugging Face account and Access Token (set as `HF_TOKEN` environment variable or passed via `--token`).
21- 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.
22
23## Procedure
24
25### 1. Installation
26
27Install the `hf` CLI by downloading the installer script, reviewing it, and running it locally.
28
29**PowerShell (Windows Host)**:
30```powershell
31$tmpdir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()))
32$installScript = Join-Path $tmpdir.FullName "hf-install.sh"
33Invoke-WebRequest -Uri "https://hf.co/cli/install.sh" -OutFile $installScript
34# Review the script before running
35Get-Content $installScript
36# Run the script (requires bash, e.g., via Git Bash or WSL)
37bash $installScript
38Remove-Item -Recurse -Force $tmpdir.FullName
39```
40
41*Note: The `hf` command replaces the deprecated `huggingface-cli` command.*
42
43### 2. Authentication
44
45Authenticate using a token from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).
46
47```powershell
48# Recommended: Set HF_TOKEN environment variable
49$env:HF_TOKEN = "YOUR_KEY"
50
51# Or login via browser
52hf auth login
53
54# Verify login
55hf auth whoami
56```
57
58### 3. Core Commands
59
60#### Downloading and Uploading
61- **Download a model**:
62 ```powershell
63 hf download openai-community/gpt2 --local-dir ./gpt2
64 ```
65- **Upload a folder**:
66 ```powershell
67 hf upload my-username/my-model ./local-folder --type model
68 ```
69- **Upload large folder (resumable)**:
70 ```powershell
71 hf upload-large-folder my-username/my-model ./large-folder --type model
72 ```
73
74#### Managing Repositories
75- **List models**:
76 ```powershell
77 hf models list --search "gpt2" --limit 10
78 ```
79- **Create a new repo**:
80 ```powershell
81 hf repos create my-username/my-new-repo --type model --private
82 ```
83
84#### Jobs
85- **Run a job**:
86 ```powershell
87 hf jobs run ubuntu:latest "echo hello" --flavor cpu-basic
88 ```
89- **Schedule a job**:
90 ```powershell
91 hf jobs scheduled run "0 0 * * *" ubuntu:latest "echo daily" --flavor cpu-basic
92 ```
93
94#### Inference Endpoints
95- **Deploy from catalog**:
96 ```powershell
97 hf endpoints catalog deploy --repo openai-community/gpt2
98 ```
99
100#### Cache Management
101- **List cache**:
102 ```powershell
103 hf cache list
104 ```
105- **Prune detached revisions**:
106 ```powershell
107 hf cache prune --dry-run
108 ```
109
110### 4. Mounting Repos as Local Filesystems
111
112Use `hf-mount` to mount Hub repositories or buckets as local filesystems.
113
114**PowerShell Installation**:
115```powershell
116$tmpdir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()))
117$installScript = Join-Path $tmpdir.FullName "hf-mount-install.sh"
118Invoke-WebRequest -Uri "https://raw.githubusercontent.com/huggingface/hf-mount/main/install.sh" -OutFile $installScript
119# Review the script
120Get-Content $installScript
121# Run the script (requires bash)
122sh $installScript
123Remove-Item -Recurse -Force $tmpdir.FullName
124```
125
126**Usage**:
127```powershell
128# Mount a repo (read-only)
129hf-mount start repo openai-community/gpt2 ./gpt2-mount
130# Mount a bucket (read-write)
131hf-mount start --hf-token $env:HF_TOKEN bucket myuser/my-bucket ./data-mount
132# Unmount
133hf-mount stop ./data-mount
134```
135
136## Pitfalls
137
138- **Deprecated CLI**: The `huggingface-cli` command is deprecated. Use `hf` instead. Auth commands are now under `hf auth` (e.g., `hf auth whoami`).
139- **Token Security**: Do not hardcode tokens in scripts. Prefer setting the `HF_TOKEN` environment variable.
140- **Large Uploads**: For large folders, use `hf upload-large-folder` instead of `hf upload` to ensure resumability.
141- **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.
142- **Irreversible Actions**: `hf repos delete` and `hf buckets delete` are irreversible. Always double-check the target ID and use `--dry-run` where available.
143- **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.
144
145## Verification
146
1471. **Check CLI Version**:
148 ```powershell
149 hf version
150 ```
151 *Expected output*: Prints the current `hf` version (generated with `huggingface_hub v1.21.0` or later).
152
1532. **Verify Authentication**:
154 ```powershell
155 hf auth whoami
156 ```
157 *Expected output*: Your Hugging Face username and account details.
158
1593. **List Cached Repositories**:
160 ```powershell
161 hf cache list
162 ```
163 *Expected output*: A list of locally cached repositories and revisions.
164
1654. **Check Environment**:
166 ```powershell
167 hf env
168 ```
169 *Expected output*: Information about the current environment, including token status and cache directory.
Kayforkind