Hugging Face CLI Update: Transition to hf Command

Hugging Face has officially renamed the huggingface-cli to hf, introducing a reorganized command structure designed for better ergonomics and discoverability. This update streamlines how users interact with the Hub, while simultaneously introducing hf jobs, a new service for executing scripts and Docker images on Hugging Face infrastructure.

New Command Structure and Syntax

The hf CLI adopts a predictable hf <resource> <action> grammar. This reorganization moves away from the previous, less consistent command structure to a more intuitive format where commands are grouped by the resource they manage.

Core Command Groups

Most functionality is now organized under specific resource headings. Key command groups include:

  • hf auth: Manages authentication, including logging in, logging out, and switching between access tokens.
  • hf cache: Handles the local cache directory.
  • hf repo: Manages repositories on the Hub.
  • hf repo-files: Manages files within a repository.
  • hf upload and hf download: These remain at the root level due to their high frequency of use.

Installation and Verification

To use the new CLI, users must install or update the huggingface_hub library:

pip install -U huggingface_hub

Successful installation can be verified by running hf version, which returns the huggingface_hub version (e.g., version 0.34.0).

Migration from huggingface-cli

While the legacy huggingface-cli remains functional to ensure a smooth transition, it is now deprecated. Using legacy commands will trigger a warning directing users to the new hf equivalent.

Authentication Changes

The most significant changes during migration affect authentication commands. Examples of the mapping include:

  • huggingface-cli login $\rightarrow$ hf auth login
  • huggingface-cli whoami $\rightarrow$ hf auth whoami
  • huggingface-cli logout $\rightarrow$ hf auth logout

Introduction of hf jobs

hf jobs is a new service allowing users to run scripts or Docker images on Hugging Face infrastructure using a pay-as-you-go billing model. This service is available exclusively to Pro users and Team or Enterprise organizations.

Capabilities and Command Set

The hf jobs command set is inspired by Docker's CLI and allows for the execution of tasks on specific hardware flavors (e.g., an A10G GPU).

Example Command:

hf jobs run --flavor=a10g-small ubuntu nvidia-smi

Available hf jobs Subcommands:

  • run: Executes a Job.
  • ps: Lists active Jobs.
  • logs: Fetches logs for a specific Job.
  • inspect: Displays detailed information about one or more Jobs.
  • cancel: Cancels a Job.
  • uv: Runs Python scripts with inline dependencies using UV on HF infrastructure.

Sources