[CLI] Migrate buckets commands to out singleton by hanouticelina · Pull Request #4111 · huggingface/huggingface_hub

hanouticelina · 2026-04-15T13:41:25Z

Part of #3979. Migrates buckets commands (create, list, info, delete, remove, move, cp) to the unified --format [auto|human|agent|json|quiet] flag and out.* methods.

Replaces --quiet with --format on all migrated commands
Uses out.result() for success messages, out.dict() for info, out.table() for bucket listing, out.confirm() for confirmations, out.hint() for hints
Adds id_key param to out.dict() for quiet mode (consistent with out.table())
sync left as-is (passes quiet/verbose to library)

_list_files and _list_buckets keep their existing output format — the ls-like flat table, -h for human-readable sizes, --tree, and the json/quiet branches are preserved as-is. Only the flag changes (--quiet → --format quiet, --format table → --format auto). The existing output worked well and we didn't want to change it unnecessarily by routing everything through out.table().

Note

Medium Risk
Moderate risk because it changes CLI flags and stdout/stderr output formatting for multiple hf buckets commands, which may break user scripts relying on previous messages or --quiet behavior.

Adds id_key support to out.dict() to make --format quiet print a single identifier (used by buckets info), routes bucket listing through out.table() (including standardized empty-results messaging), and adjusts hints/confirmations/results accordingly; tests and generated CLI docs are updated to match the new outputs and flags.

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

Consistent with `out.table()` and `out.result()`, `out.dict()` now accepts an `id_key` param. When set and mode is quiet, prints just that value instead of the full JSON.

Part of #3979. Migrates create, list, info, delete, remove, move, and cp to the unified `--format` flag and `out.*` methods. Preserves the ls-like flat table format for file listing.

bot-ci-comment · 2026-04-15T13:50:18Z

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.

Wauplin

Made a first pass, especially on the tests. Might be the worst CLI to migrate, sorry about that^^

sync left as-is (passes quiet/verbose to library)

Agree with this.
Just as a nit I think in the --plan mode we should output the --apply method just after as a hint.

Wauplin · 2026-04-15T14:02:45Z

        """
        if dataclasses.is_dataclass(data) and not isinstance(data, type):
            data = _dataclass_to_dict(data)
+        if self.mode == OutputFormatWithAuto.quiet and id_key is not None:


if --quiet but no id_key provided, what should we do? Currently we default to printing the full JSON (not a problem from this PR but this addition highlights it^^)

I don't know, for now full json is a reasonable fallback imo, quiet without id_key means the caller didn't specify what to extract, so printing everything is safer maybe ? 😄

Wauplin · 2026-04-15T14:15:58Z


    if recursive:
-        status = StatusLine(enabled=not quiet)
+        status = StatusLine(enabled=out.mode == OutputFormatWithAuto.human)


maybe we should make the StatusLine __init__ check the out.mode singleton by default instead of passing enabled=out.mode == OutputFormatWithAuto.human like here (i.e. remove the enabled parameter entirely)

agreed, but it lives in utils/_terminal.py which doesn't currently import from cli/_output.py. doing it here would create a dependency from utils -> cli. i'd rather tackle this in a followup when we implement out.status()

fine for me to do it in a later PR 👍

…ep tree --quiet behavior - Tests use --quiet instead of --format quiet (alias handled by TyperGroup) - _check_list_output uses result.stdout instead of filtering stderr lines - Restore quiet param on _build_tree so --tree --quiet shows structure only - Tree prints directly instead of mutating out.mode - Revert :>19 formatting back to explicit spaces in test expectations

hanouticelina · 2026-04-15T15:23:29Z

@Wauplin ready for a second review!

Just as a nit I think in the --plan mode we should output the --apply method just after as a hint.

added a hint in 7421ca2

Wauplin

Looks good to me! I've resolved the merge conflicts so we should be good to merge

(and let's not forget about #4111 (comment))

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

^{Reviewed by Cursor Bugbot for commit 387dcfe. Configure here.}

cursor · 2026-04-23T09:29:27Z

+        }
+        for bucket in api.list_buckets(namespace=namespace, search=search)
+    ]
+    out.table(items, alignments={"size": "right", "total_files": "right"})


Human-readable size formatting contaminates JSON output

Medium Severity

In _list_buckets, the size field is pre-formatted at dict construction time via _format_size(bucket.size, human_readable) if human_readable else bucket.size. When -h is passed, this converts the integer size to a human-readable string (e.g., "1.5 MB") in the items dict before passing it to out.table(). This means JSON output gets "size": "1.5 MB" instead of "size": 1500000, changing the field type from number to string. In the old code, _format_size was called only inside row_fn for table display, so JSON output always received raw integer values regardless of -h.

^{Reviewed by Cursor Bugbot for commit 387dcfe. Configure here.}

that's fine

cursor · 2026-04-23T09:29:27Z

    api = get_hf_api(token=token)

    if recursive:
-        status = StatusLine(enabled=not quiet)


Dry-run produces no output in json/quiet modes

Low Severity

The remove command's --dry-run path uses out.text() to display what would be deleted. Since out.text() is a no-op in json and quiet modes, running hf buckets rm ... --dry-run --format json (or --format quiet) produces zero output and returns silently. The old code always printed dry-run details regardless of the --quiet flag, so this is a behavioral regression where users get no indication of what would be deleted.

Additional Locations (1)

src/huggingface_hub/cli/buckets.py#L677-L680

^{Reviewed by Cursor Bugbot for commit 387dcfe. Configure here.}

huggingface-hub-bot · 2026-04-24T13:32:25Z

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

hanouticelina added 3 commits April 15, 2026 15:37

[CLI] Add id_key support to out.dict() for quiet mode

55052f1

Consistent with `out.table()` and `out.result()`, `out.dict()` now accepts an `id_key` param. When set and mode is quiet, prints just that value instead of the full JSON.

[CLI] Migrate buckets commands to out singleton

0b9cfe1

Part of #3979. Migrates create, list, info, delete, remove, move, and cp to the unified `--format` flag and `out.*` methods. Preserves the ls-like flat table format for file listing.

Revert unnecessary comment change in _list_files

20ffc0c

Wauplin reviewed Apr 15, 2026

View reviewed changes

hanouticelina added 2 commits April 15, 2026 16:45

Merge branch 'main' into cli-migrate-buckets-out-singleton

538afc7

hanouticelina marked this pull request as ready for review April 15, 2026 15:16

Add hint after sync --plan to show --apply command

7421ca2

hanouticelina requested a review from Wauplin April 15, 2026 15:21

Wauplin added 2 commits April 23, 2026 11:23

Merge branch 'main' into cli-migrate-buckets-out-singleton

2b34869

fix search test

387dcfe

Wauplin approved these changes Apr 23, 2026

View reviewed changes

cursor Bot reviewed Apr 23, 2026

View reviewed changes

Wauplin merged commit f1cd149 into main Apr 23, 2026
17 of 21 checks passed

Wauplin deleted the cli-migrate-buckets-out-singleton branch April 23, 2026 09:38

hanouticelina mentioned this pull request Apr 30, 2026

[CLI] Add out.status() #4171

Merged

Conversation

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

Uh oh!

Uh oh!

bot-ci-comment Bot commented Apr 15, 2026

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Wauplin Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

hanouticelina Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

hanouticelina Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

hanouticelina commented Apr 15, 2026

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Apr 23, 2026

Choose a reason for hiding this comment

Human-readable size formatting contaminates JSON output

Uh oh!

Wauplin Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Apr 23, 2026

Choose a reason for hiding this comment

Dry-run produces no output in json/quiet modes

Uh oh!

Wauplin Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hanouticelina commented Apr 15, 2026 •

edited by cursor Bot

Loading