We’re glad to announce a long-awaited quality-of-life improvement: the Hugging Face CLI has been officially renamed from huggingface-cli to hf!
So… why this modification?
Typing huggingface-cli continually gets old fast. More importantly, the CLI’s command structure became messy as recent features were added over time (upload, download, cache management, repo management, etc.). Renaming the CLI is a probability to reorganize commands right into a clearer, more consistent format.
We decided to not reinvent the wheel and as a substitute follow a widely known CLI pattern: hf . This predictable grammar makes the Hugging Face CLI more ergonomic and discoverable, while also setting the stage for upcoming features.
Getting began
To begin fidgeting with the brand new CLI, you’ll need to put in the most recent huggingface_hub version:
pip install -U huggingface_hub
and reload your terminal session. To check the install accomplished successfully, run hf version:
➜ hf version
huggingface_hub version: 0.34.0
Next, let’s explore the brand new syntax with hf --help:
➜ hf --help
usage: hf []
positional arguments:
{auth,cache,download,jobs,repo,repo-files,upload,upload-large-folder,env,version,lfs-enable-largefiles,lfs-multipart-upload}
hf command helpers
auth Manage authentication (login, logout, etc.).
cache Manage local cache directory.
download Download files from the Hub
jobs Run and manage Jobs on the Hub.
repo Manage repos on the Hub.
repo-files Manage files in a repo on the Hub.
upload Upload a file or a folder to the Hub. Advisable for single-commit uploads.
upload-large-folder
Upload a big folder to the Hub. Advisable for resumable uploads.
env Print information in regards to the environment.
version Print information in regards to the hf version.
options:
-h, --help show this help message and exit
As we will see, commands are grouped by “resource” (hf auth, hf cache, hf repo, etc.). We also surface hf upload and hf downloadat the foundation level since they’re expected to be the most-used commands.
To dive deeper into any command group, simply append --help:
➜ hf auth --help
usage: hf [] auth [-h] {login,logout,whoami,switch,list} ...
positional arguments:
{login,logout,whoami,switch,list}
Authentication subcommands
login Log in using a token from huggingface.co/settings/tokens
logout Sign off
whoami Discover which huggingface.co account you're logged in as.
switch Switch between access tokens
list List all stored access tokens
options:
-h, --help show this help message and exit
🔀 Migration
If you happen to are used to huggingface-cli, most commands will look familiar. The most important change affects authentication:
huggingface-cli login
hf auth login
huggingface-cli whoami
hf auth whoami
huggingface-cli logout
hf auth logout
All auth commands have been grouped along with the prevailing hf auth switch (to modify between different local profiles) and hf auth list (to list local profiles).
The legacy huggingface-cli stays energetic and fully-functional. We’re keeping it around to ease the transition. If you happen to use any command from the legacy CLI, you’ll see a warning that points you to the brand new CLI equivalent:
➜ huggingface-cli whoami
⚠️ Warning: 'huggingface-cli whoami' is deprecated. Use 'hf auth whoami' as a substitute.
Wauplin
orgs: huggingface,competitions,hf-internal-testing,templates,HF-test-lab,Gradio-Themes,autoevaluate,HuggingFaceM4,HuggingFaceH4,open-source-metrics,sd-concepts-library,hf-doc-build,hf-accelerate,HFSmolCluster,open-llm-leaderboard,pbdeeplinks,discord-community,llhf,sllhf,mt-metrics,DDUF,hf-inference,changelog,tiny-agents
Yet another thing… 💥 hf jobs
We couldn’t resist shipping our first dedicated command: hf jobs.
Hugging Face Jobs is a brand new service that permits you to run any script or Docker image on Hugging Face Infrastructure using the hardware flavor of your alternative. Billing is “pay-as-you-go”, meaning you pay just for the seconds you employ. Here’s find out how to launch your first command:
hf jobs run --flavor=a10g-small ubuntu nvidia-smi
The CLI is heavily inspired by Docker’s familiar commands:
➜ hf jobs --help
usage: hf <command> [] jobs [-h] {inspect,logs,ps,run,cancel,uv} ...
positional arguments:
{inspect,logs,ps,run,cancel,uv}
huggingface.co jobs related commands
inspect Display detailed information on a number of Jobs
logs Fetch the logs of a Job
ps List Jobs
run Run a Job
cancel Cancel a Job
uv Run UV scripts (Python with inline dependencies) on HF infrastructure
options:
-h, --help show this help message and exit
Learn more about Jobs by reading the guide.
Hugging Face Jobs can be found only to Pro users and Team or Enterprise organizations. Upgrade your plan to start!
