Refactor CLI implementation using Typer #3365

hanouticelina · 2025-09-15T16:52:16Z

Resolves #3363 and #3364.

This PR migrates the hf CLI from built-in argparse to Typer using idiomatic, function based commands. this significantly reduces boilerplate, making the CLI easier to maintain, less error prone, and faster to extend with new HfApi features.

What changed

new dependencies:
- typer, latest version is 0.17.4, it should be stable enough and it's widely adopted.
- click, typer s foundation, pure Python, should be stable too. latest version is 8.2.2.
- ⚠️ rich has been disabled in all cases in commit (#3364) disable rich in all cases to keep a consistent UI regardless of having rich installed or not.
Main entrypoint: cli/hf.py now uses typer.Typer and mounts:
- Top level single commands: download, upload, upload-large-folder, env, version (all defined in their respective files).
- Groups: auth, cache, repo (with tag subgroup), repo-files, jobs (with scheduled and uv subgroups).
- LFS helpers are still available but hidden in help: lfs-enable-largefiles, lfs-multipart-upload.
- All argparse classes removed and replaced by Typer commands.

> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.
  --help                Show this message and exit.

Commands:
  auth                 Manage authentication (login, logout, etc.).
  cache                Manage local cache directory.
  download             Download files from the Hub.
  env                  Print information about the environment.
  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.
  upload-large-folder  Upload a large folder to the Hub.
  version              Print information about the hf version.

tests/test_cli.py has been updated accordingly. cf the documentation to write tests for typer cli: https://typer.tiangolo.com/tutorial/testing/#about-the-appcommand-decorator.

Wauplin

Very excited about this switch! I left some very high level comments on code organization :)

src/huggingface_hub/cli/auth.py

src/huggingface_hub/cli/cache.py

Wauplin · 2025-09-15T17:15:54Z

setup.py

@@ -28,6 +28,7 @@ def get_version() -> str:

 extras["cli"] = [
    "InquirerPy==0.3.4",  # Note: installs `prompt-toolkit` in the background
+    "typer",


I would move typer to a required dependency otherwise doing pip install huggingface_hub would install a CLI but unusable (since typer would be missing).

To reduce dependency overhead, especially the rich package, let's add typer-slim which is a lighter version without rich / shellingham included. More details here: https://typer.tiangolo.com/?h=typer+slim#typer-slim

About shellingham I still think it's good to have it. Either by default or in the (soon-to-come?) "hf installer script". It's a pure-python package that helps detecting the current shell to install shell completion correctly.

(for now let's skip it but mentioning it to have it in mind)

agree! it's an oversight from me, fixed in 8ee6892

Wauplin

Looks promising assuming commands implementations have not been changed^^

(I did not review the tests yet)

src/huggingface_hub/cli/_cli_utils.py

src/huggingface_hub/cli/auth.py

src/huggingface_hub/cli/system.py

src/huggingface_hub/cli/lfs.py

src/huggingface_hub/cli/repo.py

src/huggingface_hub/cli/repo_files.py

Wauplin · 2025-09-17T09:53:26Z

src/huggingface_hub/cli/repo_files.py

+) -> None:
+    logging.set_verbosity_info()
+    repo_type = validate_repo_type(repo_type)
+    api = HfApi(token=token, library_name="hf")


That's actually a really good idea to track usage of our CLI. I think it'd be good to centralize this (some other HfApi instantiations are not defining the library_name) but can be done in a later PR. (we have a subticket about analytics specifically)

Suggested change

api = HfApi(token=token, library_name="hf")

api = HfApi(token=token, library_name="hf", library_version=__version__)

might be nice to add huggingface_hub version as well (would make things easier to works with in Kibana even though we already have the info in hf_hub user agent)

for CLI, i addressed it directly in this PR (in f2eb79b) but yes let's do the same for other HfApi instantiations

Co-authored-by: Lucain <[email protected]>

…hub into typer-migration

…_hub into typer-migration

HuggingFaceDocBuilderDev · 2025-09-17T13:08:50Z

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.

hanouticelina · 2025-09-17T13:40:48Z

This PR resolves #3370 in 3e5bc64.

Wauplin

Pre-approving ✔️ Feel free to ignore my last comments if annoying 😄

Let's get this merge soon! 🎉

(note: I also tested autocompletion locally which worked like a charm)

docs/source/en/guides/cli.md

src/huggingface_hub/cli/_cli_utils.py

src/huggingface_hub/cli/hf.py

Wauplin · 2025-09-17T14:29:56Z

src/huggingface_hub/cli/hf.py

+# top level single commands (defined in their respective files)
+app.command(
+    name="download",
+    help="Download files from the Hub.",
+)(download)
+app.command(
+    name="upload",
+    help="Upload a file or a folder to the Hub.",
+)(upload)
+app.command(
+    name="upload-large-folder",
+    help="Upload a large folder to the Hub. Recommended for resumable uploads.",
+)(upload_large_folder)
+app.command(
+    name="env",
+    help="Print information about the environment.",
+)(env)
+app.command(
+    name="version",
+    help="Print information about the hf version.",
+)(version)
+app.command(
+    name="lfs-enable-largefiles",
+    help="Configure your repository to enable upload of files > 5GB.",
+    hidden=True,
+)(lfs_enable_largefiles)
+app.command(
+    name="lfs-multipart-upload",
+    help="Upload large files to the Hub.",
+    hidden=True,
+)(lfs_multipart_upload)
+
+
+# command groups
+app.add_typer(auth_cli, name="auth")
+app.add_typer(cache_cli, name="cache")
+app.add_typer(repo_cli, name="repo")
+app.add_typer(repo_files_cli, name="repo-files")
+app.add_typer(jobs_cli, name="jobs")


Fine for me yes! Thanks for looking into this :)

src/huggingface_hub/cli/jobs.py

src/huggingface_hub/cli/repo.py

tests/test_cli.py

hanouticelina · 2025-09-18T09:35:49Z

Let's get this merged once the CI is green! 🔥

* Refactor CLI implementation using Typer (#3365) * migrate CLI to typer * (#3364) disable rich in all cases * update tests * make typer-slim a required dep * use Annotated * fix linting issues * fix tests * refactoring * update docs * use built in types * fix mypy * call whoami directly * lint * Apply suggestions from code review Co-authored-by: Lucain <[email protected]> * import Annotated from typing * Use Enums * set verbosity globally * refactor scan cache and update version docstring * centralize where Typer is defined * no need for ... * rename enum * no need for extra param name * docstring * revert * centralize arguments and options definition * add library version when initializing HfApi * add auto-completion * sort commands alphabetically * suggestions * centralize jobs params and HfApi initialization * fix --------- Co-authored-by: Lucain <[email protected]> * update docs --------- Co-authored-by: Lucain <[email protected]>

hanouticelina added 2 commits September 15, 2025 18:23

migrate CLI to typer

d46c5fa

(#3364) disable rich in all cases

93136ef

Wauplin reviewed Sep 15, 2025

View reviewed changes

src/huggingface_hub/cli/auth.py Outdated Show resolved Hide resolved

src/huggingface_hub/cli/cache.py Outdated Show resolved Hide resolved

src/huggingface_hub/cli/cache.py Outdated Show resolved Hide resolved

Wauplin reviewed Sep 15, 2025

View reviewed changes

hanouticelina added 11 commits September 16, 2025 14:05

update tests

a31db5a

make typer-slim a required dep

8ee6892

use Annotated

4437b4c

fix linting issues

cb47d09

fix tests

d8f08d5

refactoring

e5fff14

update docs

7543f3c

use built in types

f41bbcf

fix mypy

8ff6d0c

call whoami directly

53a4343

lint

f251a8a

hanouticelina marked this pull request as ready for review September 17, 2025 08:19

hanouticelina requested review from Wauplin and LysandreJik September 17, 2025 08:20

Wauplin reviewed Sep 17, 2025

View reviewed changes

hanouticelina and others added 11 commits September 17, 2025 12:00

Apply suggestions from code review

2b422ee

Co-authored-by: Lucain <[email protected]>

import Annotated from typing

ab9ac9a

Use Enums

547a436

set verbosity globally

9a65442

refactor scan cache and update version docstring

7a7190d

centralize where Typer is defined

b56c656

no need for ...

45c9fef

rename enum

a2ca057

no need for extra param name

d7823a3

Merge branch 'typer-migration' of github.com:huggingface/huggingface_…

4233fdc

…hub into typer-migration

docstring

5d18065

hanouticelina added 5 commits September 17, 2025 14:27

revert

2120e5d

centralize arguments and options definition

148299e

add library version when initializing HfApi

f2eb79b

add auto-completion

3e5bc64

Merge branch 'cli-improvements' of github.com:huggingface/huggingface…

9efaecf

…_hub into typer-migration

sort commands alphabetically

89f592e

hanouticelina requested a review from Wauplin September 17, 2025 13:38

Wauplin approved these changes Sep 17, 2025

View reviewed changes

hanouticelina added 2 commits September 17, 2025 17:03

suggestions

73aa986

centralize jobs params and HfApi initialization

e0d4820

fix

be81b46

hanouticelina merged commit c5c185d into cli-improvements Sep 18, 2025
18 checks passed

hanouticelina deleted the typer-migration branch September 18, 2025 09:57

This was referenced Sep 18, 2025

Refactor CLI implementation using Typer #3363

Closed

set rich_markup_mode=None to disable rich in all cases https://typer.tiangolo.com/tutorial/commands/help/#rich-markdown-and-markup #3364

Closed

Add autocomplete support #3370

Closed

Wauplin mentioned this pull request Sep 18, 2025

[RFC] [1.0] 🚀 huggingface_hub 1.0 release checklist #3340

Open

32 tasks

	api = HfApi(token=token, library_name="hf")
	api = HfApi(token=token, library_name="hf", library_version=__version__)

Refactor CLI implementation using Typer #3365

Refactor CLI implementation using Typer #3365

Uh oh!

Conversation

hanouticelina commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Wauplin Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

hanouticelina Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Wauplin Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

hanouticelina Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

HuggingFaceDocBuilderDev commented Sep 17, 2025

Uh oh!

hanouticelina commented Sep 17, 2025

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hanouticelina commented Sep 18, 2025

Uh oh!

Uh oh!

Uh oh!

hanouticelina commented Sep 15, 2025 •

edited

Loading