[CLI] Make --format / --json / -q global by Wauplin · Pull Request #4162 · huggingface/huggingface_hub

Wauplin · 2026-04-28T13:42:39Z

Context: let's handle `--format` globally

Benefits are:

End users: formatting options are now first-class and properly documented in --help (one consistent section per command), instead of being mixed into the regular options or only mentioned in some commands.
Maintainers: no need to remember to add format: FormatWithAutoOpt = OutputFormatWithAuto.auto (and the matching imports) when adding a new command. The flags work automatically.

Summary

Handle --format <value>, --json, and -q / --quiet globally in HFCliTyperGroup instead of declaring them on every command. The flags can appear anywhere in a leaf command's args; they're stripped and applied to the out singleton before click parses the rest.
Document them in a dedicated Formatting options section in every --help page (root, groups, and leaves).
Removed format: FormatWithAutoOpt = OutputFormatWithAuto.auto from every command (~85 occurrences across 17 files).
Legacy commands that own their own --format (hf jobs ps, hf jobs scheduled ps) keep working — the previous --json / --quiet shorthand-rewrite behaviour is preserved for them. Pass-through commands (hf extensions exec) remain untouched.
Added a short Output formatting section to the CLI guide.

Examples

# --format / --json / -q now appear in every command's --help
$ hf models ls --help
...
Formatting options:
  --format [auto|human|agent|json|quiet]
                                  Output format. Defaults to 'auto' which
                                  picks 'agent' or 'human' based on the
                                  terminal.
  -q, --quiet                     Quiet output (one ID per line). Equivalent
                                  to '--format quiet'.
  --json                          JSON output. Equivalent to '--format json'.

# Works on any command — no per-command opt-in needed
$ hf collections ls --owner nvidia --limit 2 -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171ea

# Mutually exclusive
$ hf models ls --json --format table
Error: '--json' and '--format' are mutually exclusive.

# Legacy command with its own --format keeps working
$ hf jobs ps --format '{{.id}} {{.status}}'

Note

Medium Risk
Touches CLI argument parsing and help rendering globally, so regressions could affect many commands’ option handling; changes include explicit compatibility paths for legacy/pass-through commands to reduce risk.

Overview
Makes --format, --json, and -q/--quiet global formatting flags by consuming them during command resolution and applying the chosen mode to the shared out singleton, so leaf commands no longer need to declare FormatWithAutoOpt (while pass-through commands remain untouched).

Updates help generation to add a consistent “Formatting options” section to command --help output, preserves backward compatibility for legacy commands that own their own formatting options by rewriting shorthands, and switches a few commands (e.g. hf buckets sync) to read quiet-mode from out instead of a local flag. Documentation is updated to explain the new behavior, and the generated CLI reference is refreshed accordingly.

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

Move handling of --format, --json and -q/--quiet out of every command's signature into a single pre-processor in HFCliTyperGroup that consumes them from any leaf command's args and applies them to the `out` singleton. Document them in a dedicated "Formatting options" section shown on every --help page. Legacy commands that own their own --format (hf jobs ps, scheduled ps) keep working: their shorthand rewrites are preserved. Pass-through commands (hf extensions exec) are left untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

bot-ci-comment · 2026-04-28T13:48:57Z

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

very nice improvement!

hanouticelina · 2026-04-29T13:19:28Z

+    def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        # MultiCommand.format_options writes regular options + the commands list. We
+        # insert the "Formatting options" section in between so it sits with the
+        # other options instead of below the subcommand list.
+        click.Command.format_options(self, ctx, formatter)
+        _format_formatting_options_section(formatter)
+        self.format_commands(ctx, formatter)


no strong opinion but I think it would be better to have:
hf --help -> no "Formatting options" section
hf models --help -> no section either
hf models ls --help -> shows the Fromatting section (where the flags actually work)

Suggested change

def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:

# MultiCommand.format_options writes regular options + the commands list. We

# insert the "Formatting options" section in between so it sits with the

# other options instead of below the subcommand list.

click.Command.format_options(self, ctx, formatter)

_format_formatting_options_section(formatter)

self.format_commands(ctx, formatter)

Co-authored-by: célina <[email protected]>

Remove the section from group help pages (hf --help, hf models --help) since the flags only apply to leaf commands. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Resolve conflicts: take new file-listing features from main (human_readable, tree, recursive, revision params + list_repo_files_cmd) but drop local format parameters in favor of global --format handling. Co-Authored-By: Claude Opus 4.6 <[email protected]>

hanouticelina

Thanks!

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 e44a4c6. Configure here.}

cursor · 2026-04-30T08:47:16Z

            mode = OutputFormatWithAuto.agent if is_agent() else OutputFormatWithAuto.human
        self.mode = mode
+        if mode != OutputFormatWithAuto.human:
+            disable_progress_bars()


Global flags always call set_mode(auto) disabling progress bars early

Medium Severity

Moving disable_progress_bars() into Output.set_mode() causes progress bars to be disabled at module import time for agent environments, since out = Output() is a module-level singleton that calls set_mode() in __init__. More critically, _consume_format_flags_for_leaf unconditionally calls out.set_mode(chosen_mode) even when no formatting flags are provided (chosen_mode defaults to auto). When auto resolves to agent, this disables progress bars for every leaf command invocation in agent mode — even commands where the old code would have left progress bars enabled because they never declared FormatWithAutoOpt. Previously, disable_progress_bars() was only called when a command explicitly declared and received the format parameter via the _set_output_mode callback.

Additional Locations (1)

src/huggingface_hub/cli/_cli_utils.py#L471-L472

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

that's fine now that (almost?) all commands have been migrated

@Wauplin

- Rename `secrets set` / `variables set` to `add` (mirrors add_space_secret/ add_space_variable, signals upsert vs volumes set's replace). - Add confirm + `-y/--yes` to `variables delete` for parity with `secrets delete`. Kept the warning text intentionally asymmetric: secrets says "value cannot be recovered" (true: write-only API), variables uses the shorter volumes-style phrasing (the value is visible via `ls` before deletion). - Remove now-stale per-command `--format` declarations. #4162 made --format global, so these were dead code that was breaking the import after the rebase. Per @Wauplin review at #4170 (comment 4351208819). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

huggingface-hub-bot · 2026-04-30T11:58:08Z

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

@Wauplin

* [CLI] Add hf spaces secrets and variables subgroups - `hf spaces secrets {set,delete}` wraps add_space_secret / delete_space_secret. - `hf spaces variables {set,delete,ls}` wraps add/delete_space_variable and get_space_variables. - Both `set` commands accept multiple `-s`/`-e` flags and `--secrets-file`/`--env-file` (dotenv) via the existing `parse_env_map` helper — no new parsing code. - No `secrets ls`: Hub exposes secrets as write-only (no GET endpoint). - Confirm + `--yes` on `secrets delete` only (lost-value risk); variables delete is replayable so it skips the prompt, per the #4155 rule. - `set` is upsert (one API call per key — no bulk endpoint), not replace-collection. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * [CLI] Apply review feedback: rename set→add, confirm on variables delete - Rename `secrets set` / `variables set` to `add` (mirrors add_space_secret/ add_space_variable, signals upsert vs volumes set's replace). - Add confirm + `-y/--yes` to `variables delete` for parity with `secrets delete`. Kept the warning text intentionally asymmetric: secrets says "value cannot be recovered" (true: write-only API), variables uses the shorter volumes-style phrasing (the value is visible via `ls` before deletion). - Remove now-stale per-command `--format` declarations. #4162 made --format global, so these were dead code that was breaking the import after the rebase. Per @Wauplin review at #4170 (comment 4351208819). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * Update docs/source/en/guides/cli.md Co-authored-by: Lucain <[email protected]> * Update src/huggingface_hub/cli/spaces.py Co-authored-by: Lucain <[email protected]> * [CLI] Regenerate CLI reference after suggestion commits Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]> Co-authored-by: Lucain <[email protected]>

cursor Bot reviewed Apr 28, 2026

View reviewed changes

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

Wauplin marked this pull request as draft April 28, 2026 13:48

Wauplin and others added 3 commits April 28, 2026 15:55

fix hf buckets sync

d0875c0

cli referenc

4efd4a8

Merge branch 'main' into cli-global-formatting-options

ae6173c

Wauplin marked this pull request as ready for review April 28, 2026 14:00

Wauplin requested a review from hanouticelina April 28, 2026 14:00

force auto by default

03cad1e

Wauplin mentioned this pull request Apr 28, 2026

[CLI] Add --no-truncate option to hf cache ls #4151

Draft

hanouticelina reviewed Apr 29, 2026

View reviewed changes

Wauplin and others added 2 commits April 29, 2026 17:38

Update src/huggingface_hub/cli/_cli_utils.py

42499e8

Co-authored-by: célina <[email protected]>

Update src/huggingface_hub/cli/_cli_utils.py

a4f6f45

Co-authored-by: célina <[email protected]>

cursor Bot reviewed Apr 29, 2026

View reviewed changes

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

Wauplin and others added 2 commits April 29, 2026 17:40

[CLI] Only show "Formatting options" section on leaf commands

f24b811

Remove the section from group help pages (hf --help, hf models --help) since the flags only apply to leaf commands. Co-Authored-By: Claude Opus 4.6 <[email protected]>

hanouticelina approved these changes Apr 30, 2026

View reviewed changes

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

Merge branch 'main' into cli-global-formatting-options

e44a4c6

cursor Bot reviewed Apr 30, 2026

View reviewed changes

Wauplin merged commit 6e89ade into main Apr 30, 2026
20 of 21 checks passed

Wauplin deleted the cli-global-formatting-options branch April 30, 2026 09:05

Wauplin mentioned this pull request May 5, 2026

[internal] Untrack useless files #4191

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CLI] Make --format / --json / -q global#4162

[CLI] Make --format / --json / -q global#4162
Wauplin merged 10 commits intomainfrom
cli-global-formatting-options

Wauplin commented Apr 28, 2026 •

edited by cursor Bot

Loading

Uh oh!

Uh oh!

bot-ci-comment Bot commented Apr 28, 2026

Uh oh!

hanouticelina left a comment

Uh oh!

hanouticelina Apr 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hanouticelina left a comment

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Apr 30, 2026

Uh oh!

Wauplin Apr 30, 2026

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Context: let's handle --format globally

Summary

Examples

Uh oh!

Uh oh!

bot-ci-comment Bot commented Apr 28, 2026

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

hanouticelina Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Apr 30, 2026

Choose a reason for hiding this comment

Global flags always call set_mode(auto) disabling progress bars early

Uh oh!

Wauplin Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Wauplin commented Apr 28, 2026 •

edited by cursor Bot

Loading

Context: let's handle `--format` globally

Global flags always call `set_mode(auto)` disabling progress bars early