Say hello to `hf`: a faster, friendlier Hugging Face CLI ✨

We are 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 change?

Typing huggingface-cli constantly gets old fast. More importantly, the CLI’s command structure became messy as new features were added over time (upload, download, cache management, repo management, etc.). Renaming the CLI is a chance to reorganize commands into a clearer, more consistent format.

We decided not to reinvent the wheel and instead follow a well-known CLI pattern: hf <resource> <action>. This predictable grammar makes the Hugging Face CLI more ergonomic and discoverable, while also setting the stage for upcoming features.

Getting started

To start playing with the new CLI, you’ll need to install the latest huggingface_hub version:

pip install -U huggingface_hub

and reload your terminal session. To test the install completed successfully, run hf version:

➜ hf version
huggingface_hub version: 0.34.0

Next, let’s explore the new syntax with hf --help:

As we can see, commands are grouped by "resource" (hf auth, hf cache, hf repo, etc.). We also surface hf upload and hf downloadat the root 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 <command> [<args>] 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              Log out
    whoami              Find out which huggingface.co account you are 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 are used to huggingface-cli, most commands will look familiar. The biggest change affects authentication: