Rename CLI to 'hf' + reorganize syntax

[Wauplin]

Closes #3224.
Partly inspired by #3225 but I preferred to start from scratch.

Goal is to rename huggingface-cli to hf + harmonize the syntax. We mostly follow a hf <resource> <action> [options] syntax similar to what's done by github CLI https://cli.github.com/manual/gh.

✗ hf --help
usage: hf <command> [<args>]

positional arguments:
  {auth,cache,download,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
    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. Recommended for single-commit uploads.
    upload-large-folder
                        Upload a large folder to the Hub. Recommended for resumable uploads.
    env                 Print information about the environment.
    version             Print information about the hf version.

options:
  -h, --help            show this help message and exit

Next steps will be to add new commands for a more consistent and feature-complete CLI, but story for another day!

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[LysandreJik]

Excited for this! hf feels so much more natural than huggingface-cli

One question: wouldn't it make our life simpler during maintenance and to remove the deprecation down the road, to move all commands from commands to cli while keeping a utility to still allow imports from commands, rather than copy-pasting everything?

Keeping two copies means that it's easy for the two to diverge, and I don't think we want that even through the deprecation. If the syntax is too different from the original, feel free to ignore 🤗

---

Played around with it locally, it works great! When using the deprecated API (like huggingface-cli login, you still get recommendations about the old API, maybe worth recommending only new APIs everywhere? But not key for this PR.

Ex:

- A token is already saved on your machine. Run `huggingface-cli whoami` to get more information or `huggingface-cli logout` if you want to log out.
+ A token is already saved on your machine. Run `hf auth whoami` to get more information or `hf auth logout` if you want to log out.

[julien-c]

BTW, would brew (for instance) be ok with having two aliases (the current huggingface-cli and hf)? Might be worth checking with them

[Wauplin]

Played around with it locally, it works great! When using the deprecated API (like huggingface-cli login, you still get recommendations about the old API, maybe worth recommending only new APIs everywhere? But not key for this PR.

@LysandreJik I've updated all the documentation and tips to promote hf instead of huggingface-cli 6d820c4 (retrospectively I should have done it in a follow-up PR to keep this one small-ish but too late...)

[Wauplin]

One question: wouldn't it make our life simpler during maintenance and to remove the deprecation down the road, to move all commands from commands to cli while keeping a utility to still allow imports from commands, rather than copy-pasting everything?

Keeping two copies means that it's easy for the two to diverge, and I don't think we want that even through the deprecation. If the syntax is too different from the original, feel free to ignore 🤗

@LysandreJik as mentioned in DMs, I prefer to stick with the "duplicated code" approach. Even if it's not the cleanest solution, I see a few benefits to it:

• we don't touch anything to existing logic => guarantees we don't brake anything
• CLIs have slightly diverged in syntax. If I want to keep a unified logic it makes it slightly annoying to handle both in a clean way
• having separated code makes it easy to add new commands to the new CLI without adding them to the old CLI (which we don't want to extend in order to force users to use the new one)
• • hopefully we won't change much of the legacy CLI. If there are severe bugs, we will fix them but otherwise we will simply leave it as it is now without maintaining/adding new stuff to it

[Wauplin]

BTW, would brew (for instance) be ok with having two aliases (the current huggingface-cli and hf)? Might be worth checking with them

Gentle ping to @singingwolfboy on this :)

For context, we are switching the HF CLI from huggingface-cli to hf with a slightly improved syntax. For example huggingface-cli login becomes hf auth login to be closer to the well-designed GitHub's CLI. In practice, both CLIs will exist at the same time. The legacy one huggingface-cli is deprecated and redirects to hf but will still be functional. We will remove it in the future but only after a very long deprecation cycle. We promote only hf in our docs.

@singingwolfboy my questions are now: would brew be able to support 2 command lines like this? Or would it simply be a separate brew install hf command? Also the tests in this script will probably break when we release this (huggingface-cli whoami => hf auth whoami + if using legacy CLI you'll get an additional warning message). Let me know if we can help in any way 🤗

(gentle ping to @abitrolly who has maintained the brew script lately)

[hanouticelina]

Thank you for this PR @Wauplin! i mainly reviewed the API and tested the commands locally and it looks great, i love it! 🔥

[Wauplin]

Thanks everyone! I'll merge this one now.

About brew (#3229 (comment)), I kept the previous huggingface-cli docs for now and we can adapt in a future PR. I don't want to make this one bigger than what it is now ^^

[LysandreJik]

small typo here @Wauplin

[Wauplin]

fixed directly on main, thanks 49c7979

[abitrolly]

@Wauplin huggingface-cli formula can ship both hf and huggingface-cli scripts for now. To rename the formula to hf there is an instruction https://docs.brew.sh/Rename-A-Formula

For hf I would actually prefer a proper CLI engineering approach, given the stats of the most useful commands (to make them shorter) and asking a wider community what commands they miss to work with LLMs. Also steal CLI things that people love from other projects. :D I see hf tool as not specific to huggingface, but being able to manage different kinds of open source models.

[abitrolly]

I confirm that after brew upgrade huggingface-cli both huggingface-cli and hf commands work.

✗ brew info huggingface-cli
==> huggingface-cli: stable 0.34.1 (bottled)
Client library for huggingface.co hub
https://huggingface.co/docs/huggingface_hub/guides/cli
Installed
/home/linuxbrew/.linuxbrew/Cellar/huggingface-cli/0.34.1 (1,001 files, 19MB) *
  Poured from bottle using the formulae.brew.sh API on 2025-07-25 at 21:31:39
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/h/huggingface-cli.rb
License: Apache-2.0
==> Dependencies
Build: pkgconf ✔, rust ✔
Required: certifi ✔, git-lfs ✔, libyaml ✔, python@3.13 ✔, openssl@3 ✔
==> Analytics
install: 3,992 (30 days), 11,433 (90 days), 28,179 (365 days)
install-on-request: 3,990 (30 days), 11,418 (90 days), 28,081 (365 days)
build-error: 2 (30 days)

✗ which hf
/home/linuxbrew/.linuxbrew/bin/hf
✗ which huggingface-cli
/home/linuxbrew/.linuxbrew/bin/huggingface-cli

✗ hf
usage: hf <command> [<args>]

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. Recommended for single-commit uploads.
    upload-large-folder
                        Upload a large folder to the Hub. Recommended for resumable uploads.
    env                 Print information about the environment.
    version             Print information about the hf version.

options:
  -h, --help            show this help message and exit

✗ huggingface-cli
⚠️  Warning: 'huggingface-cli' is deprecated. Use 'hf' instead.
usage: huggingface-cli <command> [<args>]

positional arguments:
  {download,upload,repo-files,env,login,whoami,logout,auth,repo,lfs-enable-largefiles,lfs-multipart-upload,scan-cache,delete-cache,tag,version,upload-large-folder}
                        huggingface-cli command helpers
    download            Download files from the Hub
    upload              Upload a file or a folder to a repo on the Hub
    repo-files          Manage files in a repo on the Hub
    env                 Print information about the environment.
    login               Log in using a token from huggingface.co/settings/tokens
    whoami              Find out which huggingface.co account you are logged in as.
    logout              Log out
    auth                Other authentication related commands
    repo                {create} Commands to interact with your huggingface.co repos.
    lfs-enable-largefiles
                        Configure your repository to enable upload of files > 5GB.
    scan-cache          Scan cache directory.
    delete-cache        Delete revisions from the cache directory.
    tag                 (create, list, delete) tags for a repo in the hub
    version             Print information about the huggingface-cli version.
    upload-large-folder
                        Upload a large folder to a repo on the Hub

options:
  -h, --help            show this help message and exit

Next I will try to rename the formula to hf.

[abitrolly]

PR for renaming brew formula - Homebrew/homebrew-core#231234

[Wauplin]

Thanks a lot @abitrolly for providing your help on this! Given the discussion in Homebrew/homebrew-core#231234, I think it's fine to keep brew install huggingface-cli (which already works :) ) even though the CLI is named hf. A brew install hf command would have been cool but I understand the arguments there. A big advantage of keeping brew install huggingface-cli is that we won't need to update any documentation / it won't break anything in the wild.

Note: it's still possible that if (when? 😁) hf become popular among devs, we will revisit this.