[CLI] Migrate `hf cache` to `out` singleton by hanouticelina · Pull Request #4070 · huggingface/huggingface_hub

hanouticelina · 2026-04-08T16:28:56Z

Part of #3979

This PR migrates all cache subcommands (ls, rm, prune, verify) to the out singleton.

it introduces some notable breaking changes, in addition to those that affects all migrated commands (e.g. -q/--quiet replaced by --format quiet, errors and warnings goes to stderr instead of stdout):

hf cache ls --format json:

id field added (e.g. model/unsloth/Qwen3.5-35B-A3B-GGUF)
size_on_disk (int, bytes) replaced by size (formatted string, e.g. "1.2 GB")
last_accessed and last_modified changed from float timestamps to formatted strings (e.g. "3 days ago")

Note

Medium Risk
This changes hf cache CLI flags and output formats (including --quiet removal and different JSON/table fields), which can break user scripts and tests that parse stdout/stderr.

Overview
Migrates all hf cache subcommands (ls, rm, prune, verify) to the out output singleton and standardizes output handling via --format [agent|auto|human|json|quiet].

This replaces the legacy --quiet flag with --format quiet, updates ls rendering to go through out.table (including revised JSON/table fields such as adding id and emitting human-formatted size/time strings), and routes warnings/errors/success messages through out (changing stdout/stderr behavior).

Docs and CLI tests are updated to reflect the new --format option and the adjusted output assertions.

^{Reviewed by Cursor Bugbot for commit 09df44d. Bugbot is set up for automated code reviews on this repo. Configure here.}

bot-ci-comment · 2026-04-08T16:35:00Z

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 · 2026-04-09T14:58:11Z

@cursoragent review

cursor · 2026-04-09T14:58:21Z

The PR already exists and I don't need to update its title or body — my commit is already pushed. Here's my review summary:

I reviewed the PR and found two functional issues that I fixed:

1. out.result() calls had no data kwargs — In rm, prune, and verify, out.result(message) was called without structured data kwargs. Looking at Output.result() in _output.py, when data is empty: json mode emits an empty string, quiet mode emits nothing, and agent mode falls back to the message string. I added meaningful kwargs (repos_deleted, revisions_deleted, freed, repo_id, checked, etc.) so all output modes produce useful output.

2. verify error details used out.text() which is a no-op in json/quiet modes — Mismatch details, missing file lists, and extra file lists were printed via out.text(), which silently drops content in json and quiet modes. Changed these to out.error() so verification failure details are always visible (on stderr). Updated corresponding test assertions to check result.output (stdout+stderr combined) instead of result.stdout.

All 221 CLI tests pass, make style and make quality are clean.

…failures - out.result() in rm, prune, verify now passes structured data kwargs so json/quiet modes emit useful output instead of empty strings - verify mismatch/missing/extra details now use out.error() instead of out.text() so they are visible in all output modes (text is a no-op in json/quiet) - update test assertions to use result.output (stdout+stderr) for error messages that now go to stderr via out.error() Co-authored-by: célina <[email protected]>

hanouticelina · 2026-04-09T15:28:52Z

@cursoragent revert 2f95baa

cursor · 2026-04-09T15:28:59Z

Reverted commit 2f95baa and pushed the revert to the branch.

… verify failures" This reverts commit 2f95baa.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 09df44d. Configure here.}

…uggingface_hub into cli-migrate-commands-part3

hanouticelina · 2026-04-10T08:13:03Z

@Wauplin one thing i noticed is that in json or agent, library level logger.info() messages can leak into stdout.

x hf cache rm model/m42-health/Llama3-Med42-70B --json --yes
Delete repo: /Users/hcelina/.cache/huggingface/hub/models--m42-health--Llama3-Med42-70B
Cache deletion done. Saved 8.8K.
{"repos_deleted": 1, "revisions_deleted": 1, "freed": "8.8K"} # in json mode we only want the dict

I don't think we should disable info logging in _output.py since set_mode() is called at import time. instead, we disable it in the _set_output_mode callback when mode is not human. what do you think?

Wauplin

Tested locally and approved! Minor comment + out.confirm can be handled separately

one thing i noticed is that in json or agent, library level logger.info() messages can leak into stdout.
I don't think we should disable info logging in _output.py since set_mode() is called at import time. instead, we disable it in the _set_output_mode callback when mode is not human. what do you think?

Yes indeed I see the problem. What do you think of redirecting logger.info() to stderr instead of stdout when in agent/json mode? so that the agent still have the info but we do not pollute the stdout. (and yes agree in doing it at runtime in _set_output_mode).

Otherwise I'm ok to disable logs entirely, I'm just unsure what we will be missing.

Wauplin · 2026-04-10T09:39:52Z

+        )
        return

    if not yes and not typer.confirm("Proceed with deletion?", default=False):


note: change typer.confirm with out.confirm (once implemented) so that in agent mode with gracefully raise error (mentioned in #3979)

Wauplin · 2026-04-10T09:40:05Z

+        )
        return

    if not yes and not typer.confirm("Proceed?"):


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

hanouticelina · 2026-04-10T12:48:49Z

@Wauplin actually I'm dumb (and tricked by Opus 🙃), logger.info() messages already go to stderr (Python's StreamHandler defaults to stderr), stdout is clean, so all good!

> hf cache rm model/bartowski/Qwen2.5-Coder-14B-GGUF --yes --format json 2>/dev/null
{"repos_deleted": 1, "revisions_deleted": 1, "freed": "15.7G"}

huggingface-hub-bot · 2026-04-16T13:07:54Z

This PR has been shipped as part of the v1.11.0 release.

hanouticelina added 6 commits April 8, 2026 15:38

migrate cache CLI

de088cb

fix

2be2e29

add --format params

26969db

docs

a31e3e4

re-add repo-type to dict

0eb0599

missing data

1606487

Merge branch 'main' into cli-migrate-commands-part3

9f41285

hanouticelina marked this pull request as ready for review April 9, 2026 14:57

hanouticelina requested a review from Wauplin April 9, 2026 14:57

hanouticelina and others added 8 commits April 9, 2026 16:59

Merge branch 'main' into cli-migrate-commands-part3

87d68f9

migrate cache CLI

49090a7

fix

738cd60

add --format params

2a08885

docs

278360d

re-add repo-type to dict

0b6ab03

missing data

cd92d0e

Revert "fix: pass data kwargs to out.result() and use out.error() for…

09df44d

… verify failures" This reverts commit 2f95baa.

hanouticelina marked this pull request as draft April 9, 2026 15:32

cursor Bot reviewed Apr 9, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/cache.py Outdated

hanouticelina added 3 commits April 9, 2026 17:42

add kwargs

45b7843

Merge branch 'cli-migrate-commands-part3' of github.com:huggingface/h…

acd0aaf

…uggingface_hub into cli-migrate-commands-part3

dry-run json mode

9a42073

Merge branch 'main' into cli-migrate-commands-part3

7d9c55a

hanouticelina marked this pull request as ready for review April 10, 2026 08:13

Wauplin approved these changes Apr 10, 2026

View reviewed changes

Update src/huggingface_hub/cli/cache.py

2b6778b

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

hanouticelina merged commit 52503dd into main Apr 10, 2026
17 of 20 checks passed

hanouticelina deleted the cli-migrate-commands-part3 branch April 10, 2026 12:54

Conversation

hanouticelina commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bot-ci-comment Bot commented Apr 8, 2026

Uh oh!

hanouticelina commented Apr 9, 2026

Uh oh!

cursor Bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hanouticelina commented Apr 9, 2026

Uh oh!

cursor Bot commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hanouticelina commented Apr 10, 2026

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Wauplin Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hanouticelina commented Apr 10, 2026

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hanouticelina commented Apr 8, 2026 •

edited

Loading

cursor Bot commented Apr 9, 2026 •

edited

Loading

cursor Bot commented Apr 9, 2026 •

edited

Loading