From 39305522a59cf51e423c1f4fdb593c1195ddba7e Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 16:42:17 +0200
Subject: [PATCH 01/13] [CLI] Add `hf upgrade` + drop interactive update prompt

- Replace the blocking Y/n auto-update prompt with a one-line stderr warning pointing to `hf upgrade`
- New `hf upgrade` command (under `help` topic) that picks the right command for the detected install method (brew/hf_installer/pip)
- New `HF_HUB_NO_UPDATE_CHECK` env var to silence the startup PyPI check entirely (handy for CI / quieter shells)
---
 docs/source/en/guides/cli.md                  | 12 +++
 docs/source/en/package_reference/cli.md       | 15 +++
 .../environment_variables.md                  |  6 ++
 src/huggingface_hub/cli/_cli_utils.py         | 91 ++++---------------
 src/huggingface_hub/cli/hf.py                 |  3 +-
 src/huggingface_hub/cli/skills.py             |  1 +
 src/huggingface_hub/cli/system.py             | 12 +++
 src/huggingface_hub/constants.py              |  3 +
 8 files changed, 69 insertions(+), 74 deletions(-)

diff --git a/docs/source/en/guides/cli.md b/docs/source/en/guides/cli.md
index b66cc0abe9..a19461a298 100644
--- a/docs/source/en/guides/cli.md
+++ b/docs/source/en/guides/cli.md
@@ -114,6 +114,18 @@ You can also install the CLI using [Homebrew](https://brew.sh/):
 
 Check out the Homebrew huggingface page [here](https://formulae.brew.sh/formula/hf) for more details.
 
+### Upgrading
+
+To upgrade to the latest version, run:
+
+```bash
+>>> hf upgrade
+```
+
+This detects how `hf` was installed (Homebrew, standalone installer, or pip) and runs the matching upgrade command.
+
+By default, the CLI also prints a one-line yellow warning to stderr when a newer version is available on PyPI. To silence it (e.g. in offline CI), set `HF_HUB_NO_UPDATE_CHECK=1`.
+
 ## hf auth login
 
 In many cases, you must be logged in to a Hugging Face account to interact with the Hub (download private repos, upload files, create PRs, etc.). To do so, you need a [User Access Token](https://huggingface.co/docs/hub/security-tokens) from your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is used to authenticate your identity to the Hub. Make sure to set a token with write access if you want to upload or modify content.
diff --git a/docs/source/en/package_reference/cli.md b/docs/source/en/package_reference/cli.md
index dd48817d3a..a17236fc87 100644
--- a/docs/source/en/package_reference/cli.md
+++ b/docs/source/en/package_reference/cli.md
@@ -42,6 +42,7 @@ $ hf [OPTIONS] COMMAND [ARGS]...
 * `skills`: Manage skills for AI assistants.
 * `spaces`: Interact with spaces on the Hub.
 * `sync`: Sync files between local directory and a...
+* `upgrade`: Upgrade the `hf` CLI to the latest version.
 * `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.
@@ -3763,6 +3764,20 @@ $ hf sync [OPTIONS] [SOURCE] [DEST]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
+## `hf upgrade`
+
+Upgrade the `hf` CLI to the latest version.
+
+**Usage**:
+
+```console
+$ hf upgrade [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
 ## `hf upload`
 
 Upload a file or a folder to the Hub. Recommended for single-commit uploads.
diff --git a/docs/source/en/package_reference/environment_variables.md b/docs/source/en/package_reference/environment_variables.md
index 851ddc74a1..f943096277 100644
--- a/docs/source/en/package_reference/environment_variables.md
+++ b/docs/source/en/package_reference/environment_variables.md
@@ -185,6 +185,12 @@ You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally dis
 
 Set to disable using `hf-xet`, even if it is available in your Python environment. This is since `hf-xet` will be used automatically if it is found, this allows explicitly disabling its usage. If you are disabling Xet, please consider [filing an issue and including the diagnostics](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) information to help us understand why Xet is not working for you.
 
+### HF_HUB_NO_UPDATE_CHECK
+
+By default, the `hf` CLI checks PyPI for a newer release at startup (at most once every 24 hours) and prints a one-line yellow warning to stderr when one is available, suggesting `hf upgrade`. The check is already a no-op on dev and pre-release versions.
+
+Set `HF_HUB_NO_UPDATE_CHECK=1` to skip the PyPI request and silence the warning entirely. Useful in offline CI environments or when you prefer a quieter shell output.
+
 ### HF_HUB_ENABLE_HF_TRANSFER
 
 > [!WARNING]
diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index e6b7944a80..f61773ae6d 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -35,7 +35,6 @@
 from huggingface_hub import Volume, __version__, constants
 from huggingface_hub.errors import CLIError
 from huggingface_hub.utils import (
-    ANSI,
     disable_progress_bars,
     get_session,
     hf_raise_for_status,
@@ -953,10 +952,10 @@ def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> Non
     """
     Check whether a newer version of a library is available on PyPI.
 
-    If a newer version is found and stdin/stderr are attached to a TTY, prompt the user to update interactively.
-    Otherwise (non-TTY or update command cannot be determined), print a warning to stderr.
+    If a newer version is found, print a yellow warning to stderr pointing at `hf upgrade`.
 
     If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
+    If `HF_HUB_NO_UPDATE_CHECK` is set, the check is skipped entirely.
 
     This function is called at the entry point of the CLI. It only performs the check once every 24 hours, and any error
     during the check is caught and logged, to avoid breaking the CLI.
@@ -972,6 +971,9 @@ def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> Non
 
 
 def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> None:
+    if constants.HF_HUB_NO_UPDATE_CHECK:
+        return
+
     current_version = importlib.metadata.version(library)
 
     # Skip if current version is a pre-release or dev version
@@ -1002,81 +1004,24 @@ def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> No
     else:
         update_command = _get_transformers_update_command()
 
-    if sys.stdin.isatty() and sys.stderr.isatty() and update_command is not None:
-        _prompt_autoupdate(library, current_version, latest_version, update_command)
-    else:
-        display_cmd = " ".join(update_command) if update_command else None
-        update_hint = f"To update, run: {ANSI.bold(display_cmd)}" if display_cmd else ""
-        click.echo(
-            ANSI.yellow(
-                f"A new version of {library} ({latest_version}) is available! "
-                f"You are using version {current_version}." + (f"\n{update_hint}" if update_hint else "") + "\n"
-            ),
-            file=sys.stderr,
-        )
+    message = f"A new version of {library} ({latest_version}) is available! You are using version {current_version}."
+    if update_command is not None:
+        message += "\nTo update, run: hf upgrade"
+    out.warning(message)
 
 
-def _prompt_autoupdate(
-    library: str,
-    current_version: str,
-    latest_version: str,
-    update_command: list[str],
-) -> None:
-    """Interactively ask the user if they want to update, and run the update command if accepted.
+def run_upgrade() -> int:
+    """Run the install-method-appropriate upgrade command for the `hf` CLI.
 
-    After a successful update the CLI exits so the user can re-run their command with the new version.
-    All output goes to stderr to keep stdout clean for command output.
+    Raises CLIError if the installation method can't be determined.
+    Returns the subprocess exit code on success/failure of the upgrade itself.
     """
-    display_cmd = " ".join(update_command)
-
-    click.echo("", file=sys.stderr)
-    click.echo(
-        ANSI.yellow(f"  A new version of {library} is available: {current_version} → {latest_version}"),
-        file=sys.stderr,
-    )
-    click.echo("", file=sys.stderr)
-
-    click.echo(
-        ANSI.yellow("  Do you want to update now? [Y/n] ") + ANSI.gray(f"({display_cmd})") + " ",
-        file=sys.stderr,
-        nl=False,
-    )
-    try:
-        raw_answer = sys.stdin.readline()
-    except (EOFError, KeyboardInterrupt):
-        click.echo("", file=sys.stderr)
-        return
-
-    if raw_answer == "":
-        # EOF (e.g. Ctrl+D) — treat as cancellation, not acceptance
-        click.echo("", file=sys.stderr)
-        return
-
-    answer = raw_answer.strip().lower()  # Note: if user press 'Enter', raw_answer is `\n`
-    if answer in ("", "y", "yes"):
-        click.echo("", file=sys.stderr)
-        click.echo(ANSI.gray(f"  Running: {display_cmd}"), file=sys.stderr)
-        click.echo("", file=sys.stderr)
-        returncode = subprocess.call(update_command)
-        if returncode == 0:
-            click.echo("", file=sys.stderr)
-            click.echo(
-                ANSI.green(f"  ✓ Successfully updated {library} to {latest_version}. Please re-run your command."),
-                file=sys.stderr,
-            )
-            raise SystemExit(0)
-        else:
-            click.echo("", file=sys.stderr)
-            click.echo(
-                ANSI.red(f"  ✗ Update failed (exit code {returncode}). Please update manually."),
-                file=sys.stderr,
-            )
-    else:
-        click.echo(
-            ANSI.gray(f"  Skipped. You can update later with: {display_cmd}"),
-            file=sys.stderr,
+    cmd = _get_huggingface_hub_update_command()
+    if cmd is None:
+        raise CLIError(
+            "Cannot determine how to upgrade huggingface_hub (unknown installation method). Please upgrade manually."
         )
-    click.echo("", file=sys.stderr)
+    return subprocess.call(cmd)
 
 
 def _get_huggingface_hub_update_command() -> list[str] | None:
diff --git a/src/huggingface_hub/cli/hf.py b/src/huggingface_hub/cli/hf.py
index b4eb37502c..e35da70dba 100644
--- a/src/huggingface_hub/cli/hf.py
+++ b/src/huggingface_hub/cli/hf.py
@@ -42,7 +42,7 @@
 from huggingface_hub.cli.repos import repos_cli
 from huggingface_hub.cli.skills import skills_cli
 from huggingface_hub.cli.spaces import spaces_cli
-from huggingface_hub.cli.system import env, version
+from huggingface_hub.cli.system import env, upgrade, version
 from huggingface_hub.cli.upload import UPLOAD_EXAMPLES, upload
 from huggingface_hub.cli.upload_large_folder import UPLOAD_LARGE_FOLDER_EXAMPLES, upload_large_folder
 from huggingface_hub.cli.webhooks import webhooks_cli
@@ -80,6 +80,7 @@ def app_callback(
 app.command(examples=UPLOAD_LARGE_FOLDER_EXAMPLES)(upload_large_folder)
 
 app.command(topic="help")(env)
+app.command(topic="help")(upgrade)
 app.command(topic="help")(version)
 
 app.command(hidden=True)(lfs_enable_largefiles)
diff --git a/src/huggingface_hub/cli/skills.py b/src/huggingface_hub/cli/skills.py
index 2b09d467e1..1b8e9b2a19 100644
--- a/src/huggingface_hub/cli/skills.py
+++ b/src/huggingface_hub/cli/skills.py
@@ -101,6 +101,7 @@
 
 - Use `hf <command> --help` for full options, descriptions, usage, and real-world examples
 - Authenticate with `HF_TOKEN` env var (recommended) or with `--token`
+- Upgrade the CLI with `hf upgrade` (uses the correct command for the detected install method)
 """
 
 CENTRAL_LOCAL = Path(".agents/skills")
diff --git a/src/huggingface_hub/cli/system.py b/src/huggingface_hub/cli/system.py
index ede66925bb..fa99e6b7fb 100644
--- a/src/huggingface_hub/cli/system.py
+++ b/src/huggingface_hub/cli/system.py
@@ -16,6 +16,8 @@
 from huggingface_hub import __version__
 
 from ..utils import dump_environment_info
+from ._cli_utils import run_upgrade
+from ._output import out
 
 
 def env() -> None:
@@ -26,3 +28,13 @@ def env() -> None:
 def version() -> None:
     """Print information about the hf version."""
     print(__version__)
+
+
+def upgrade() -> None:
+    """Upgrade the `hf` CLI to the latest version."""
+    returncode = run_upgrade()
+    if returncode == 0:
+        out.hint(
+            "You may also want to run `hf skills upgrade` to refresh any installed skills "
+            "so your AI agent sees the latest command surface."
+        )
diff --git a/src/huggingface_hub/constants.py b/src/huggingface_hub/constants.py
index 568843c17e..80a402f6b6 100644
--- a/src/huggingface_hub/constants.py
+++ b/src/huggingface_hub/constants.py
@@ -194,6 +194,9 @@ def list_files(repo_id: str):
 # Check is performed once per 24 hours at most.
 CHECK_FOR_UPDATE_DONE_PATH = os.path.join(HF_HOME, ".check_for_update_done")
 
+# Set to skip the CLI update check (PyPI query + "new version available" warning at startup).
+HF_HUB_NO_UPDATE_CHECK = _is_true(os.environ.get("HF_HUB_NO_UPDATE_CHECK"))
+
 # If set, log level will be set to DEBUG and all requests made to the Hub will be logged
 # as curl commands for reproducibility.
 HF_DEBUG = _is_true(os.environ.get("HF_DEBUG"))

From 2ecd462a13c0ccd8a272041b34787eca2f3569bf Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 16:47:04 +0200
Subject: [PATCH 02/13] [CLI] Mention `hf upgrade` in the installation guide

---
 docs/source/en/installation.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md
index 380c62aa5a..ad16b75822 100644
--- a/docs/source/en/installation.md
+++ b/docs/source/en/installation.md
@@ -118,6 +118,8 @@ On Windows:
 powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
 ```
 
+To upgrade an existing install, run `hf upgrade` — it detects how `hf` was installed (standalone installer, Homebrew, or pip) and runs the matching command.
+
 ## Install with conda
 
 If you are more familiar with it, you can install `huggingface_hub` using the [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub):

From f67c00da8beb4e75a8886d8f234e3940d81ee042 Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 16:47:52 +0200
Subject: [PATCH 03/13] gint, not warning

---
 src/huggingface_hub/cli/_cli_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index f61773ae6d..2f90c2e68e 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -1007,7 +1007,7 @@ def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> No
     message = f"A new version of {library} ({latest_version}) is available! You are using version {current_version}."
     if update_command is not None:
         message += "\nTo update, run: hf upgrade"
-    out.warning(message)
+    out.hint(message)
 
 
 def run_upgrade() -> int:

From be4ab97ef1948c4a518e6aacd0156e958e44af0d Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 16:50:20 +0200
Subject: [PATCH 04/13] HF_HUB_DISABLE_UPDATE_CHECK

---
 .../en/package_reference/environment_variables.md      | 10 +++++-----
 src/huggingface_hub/cli/_cli_utils.py                  |  4 ++--
 src/huggingface_hub/constants.py                       |  2 +-
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/source/en/package_reference/environment_variables.md b/docs/source/en/package_reference/environment_variables.md
index f943096277..8adad7ccd2 100644
--- a/docs/source/en/package_reference/environment_variables.md
+++ b/docs/source/en/package_reference/environment_variables.md
@@ -181,15 +181,15 @@ Each library defines its own policy (i.e. which usage to monitor) but the core i
 
 You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally disable telemetry.
 
-### HF_HUB_DISABLE_XET
+### HF_HUB_DISABLE_UPDATE_CHECK
 
-Set to disable using `hf-xet`, even if it is available in your Python environment. This is since `hf-xet` will be used automatically if it is found, this allows explicitly disabling its usage. If you are disabling Xet, please consider [filing an issue and including the diagnostics](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) information to help us understand why Xet is not working for you.
+By default, the `hf` CLI checks PyPI for a newer release at startup (at most once every 24 hours) and prints a one-line yellow warning to stderr when one is available, suggesting `hf upgrade`. The check is already a no-op on dev and pre-release versions.
 
-### HF_HUB_NO_UPDATE_CHECK
+Set `HF_HUB_DISABLE_UPDATE_CHECK=1` to skip the PyPI request and silence the warning entirely. Useful in offline CI environments or when you prefer a quieter shell output.
 
-By default, the `hf` CLI checks PyPI for a newer release at startup (at most once every 24 hours) and prints a one-line yellow warning to stderr when one is available, suggesting `hf upgrade`. The check is already a no-op on dev and pre-release versions.
+### HF_HUB_DISABLE_XET
 
-Set `HF_HUB_NO_UPDATE_CHECK=1` to skip the PyPI request and silence the warning entirely. Useful in offline CI environments or when you prefer a quieter shell output.
+Set to disable using `hf-xet`, even if it is available in your Python environment. This is since `hf-xet` will be used automatically if it is found, this allows explicitly disabling its usage. If you are disabling Xet, please consider [filing an issue and including the diagnostics](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) information to help us understand why Xet is not working for you.
 
 ### HF_HUB_ENABLE_HF_TRANSFER
 
diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index 2f90c2e68e..eee5b5f21e 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -955,7 +955,7 @@ def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> Non
     If a newer version is found, print a yellow warning to stderr pointing at `hf upgrade`.
 
     If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
-    If `HF_HUB_NO_UPDATE_CHECK` is set, the check is skipped entirely.
+    If `HF_HUB_DISABLE_UPDATE_CHECK` is set, the check is skipped entirely.
 
     This function is called at the entry point of the CLI. It only performs the check once every 24 hours, and any error
     during the check is caught and logged, to avoid breaking the CLI.
@@ -971,7 +971,7 @@ def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> Non
 
 
 def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> None:
-    if constants.HF_HUB_NO_UPDATE_CHECK:
+    if constants.HF_HUB_DISABLE_UPDATE_CHECK:
         return
 
     current_version = importlib.metadata.version(library)
diff --git a/src/huggingface_hub/constants.py b/src/huggingface_hub/constants.py
index 80a402f6b6..f851d3f748 100644
--- a/src/huggingface_hub/constants.py
+++ b/src/huggingface_hub/constants.py
@@ -195,7 +195,7 @@ def list_files(repo_id: str):
 CHECK_FOR_UPDATE_DONE_PATH = os.path.join(HF_HOME, ".check_for_update_done")
 
 # Set to skip the CLI update check (PyPI query + "new version available" warning at startup).
-HF_HUB_NO_UPDATE_CHECK = _is_true(os.environ.get("HF_HUB_NO_UPDATE_CHECK"))
+HF_HUB_DISABLE_UPDATE_CHECK = _is_true(os.environ.get("HF_HUB_DISABLE_UPDATE_CHECK"))
 
 # If set, log level will be set to DEBUG and all requests made to the Hub will be logged
 # as curl commands for reproducibility.

From 0d26a8233508b20379acb3f738cece2db462c0c8 Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 16:51:19 +0200
Subject: [PATCH 05/13] [CLI] Propagate subprocess exit code from `hf upgrade`

Surface non-zero pip/brew/installer exits via `typer.Exit` so scripts and CI can detect upgrade failures. Matches the convention in extensions.py.
---
 src/huggingface_hub/cli/system.py | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/huggingface_hub/cli/system.py b/src/huggingface_hub/cli/system.py
index fa99e6b7fb..92d6b862c2 100644
--- a/src/huggingface_hub/cli/system.py
+++ b/src/huggingface_hub/cli/system.py
@@ -13,6 +13,8 @@
 # limitations under the License.
 """Contains commands to print information about the environment and version."""
 
+import typer
+
 from huggingface_hub import __version__
 
 from ..utils import dump_environment_info
@@ -33,8 +35,9 @@ def version() -> None:
 def upgrade() -> None:
     """Upgrade the `hf` CLI to the latest version."""
     returncode = run_upgrade()
-    if returncode == 0:
-        out.hint(
-            "You may also want to run `hf skills upgrade` to refresh any installed skills "
-            "so your AI agent sees the latest command surface."
-        )
+    if returncode != 0:
+        raise typer.Exit(code=returncode)
+    out.hint(
+        "You may also want to run `hf skills upgrade` to refresh any installed skills "
+        "so your AI agent sees the latest command surface."
+    )

From 2a093477edd84b02b03f67f9c79a5f8e0ed1115b Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 16:53:16 +0200
Subject: [PATCH 06/13] better

---
 src/huggingface_hub/cli/_cli_utils.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index eee5b5f21e..11d9d10399 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -1006,7 +1006,11 @@ def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> No
 
     message = f"A new version of {library} ({latest_version}) is available! You are using version {current_version}."
     if update_command is not None:
-        message += "\nTo update, run: hf upgrade"
+        match library:
+            case "huggingface_hub":
+                message += "\nTo update, run: hf upgrade"
+            case _:
+                message += f"\nTo update, run: {update_command}"
     out.hint(message)
 
 

From 236062914fbe54bcb939d8efe972e12b4569aaa9 Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 17:04:09 +0200
Subject: [PATCH 07/13] a

---
 docs/source/en/guides/cli.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/en/guides/cli.md b/docs/source/en/guides/cli.md
index a19461a298..9ddead15bf 100644
--- a/docs/source/en/guides/cli.md
+++ b/docs/source/en/guides/cli.md
@@ -124,7 +124,7 @@ To upgrade to the latest version, run:
 
 This detects how `hf` was installed (Homebrew, standalone installer, or pip) and runs the matching upgrade command.
 
-By default, the CLI also prints a one-line yellow warning to stderr when a newer version is available on PyPI. To silence it (e.g. in offline CI), set `HF_HUB_NO_UPDATE_CHECK=1`.
+By default, the CLI also prints a one-line yellow warning to stderr when a newer version is available on PyPI. To silence it (e.g. in offline CI), set `HF_HUB_DISABLE_UPDATE_CHECK=1`.
 
 ## hf auth login
 

From 5eb91832aa7bf35bdd0c23cc1b52952245ed956c Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 17:05:25 +0200
Subject: [PATCH 08/13] docstring

---
 src/huggingface_hub/cli/_cli_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index 11d9d10399..7ab2811601 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -952,7 +952,7 @@ def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> Non
     """
     Check whether a newer version of a library is available on PyPI.
 
-    If a newer version is found, print a yellow warning to stderr pointing at `hf upgrade`.
+    If a newer version is found, print a hint pointing at `hf upgrade`.
 
     If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
     If `HF_HUB_DISABLE_UPDATE_CHECK` is set, the check is skipped entirely.

From cf97f8301168cfbd698d599b9224897647f83c11 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 22 Apr 2026 15:08:06 +0000
Subject: [PATCH 09/13] [CLI] Fix list repr in transformers update command
 message

Join the list[str] update_command with spaces before interpolating
into the user-facing message, so it displays as a shell command
rather than a Python repr like ['python', '-m', 'pip', ...].

Co-authored-by: Lucain <Wauplin@users.noreply.github.com>
---
 src/huggingface_hub/cli/_cli_utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index 7ab2811601..f0916eeea1 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -1010,7 +1010,7 @@ def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> No
             case "huggingface_hub":
                 message += "\nTo update, run: hf upgrade"
             case _:
-                message += f"\nTo update, run: {update_command}"
+                message += f"\nTo update, run: {' '.join(update_command)}"
     out.hint(message)
 
 

From 699111f8e65cebd9dd3cd77537a5d99df2c48443 Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 17:27:05 +0200
Subject: [PATCH 10/13] hf update

---
 docs/source/en/guides/cli.md                              | 6 +++---
 docs/source/en/package_reference/environment_variables.md | 2 +-
 src/huggingface_hub/cli/_cli_utils.py                     | 4 ++--
 src/huggingface_hub/cli/skills.py                         | 2 +-
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/source/en/guides/cli.md b/docs/source/en/guides/cli.md
index 9ddead15bf..4975f91887 100644
--- a/docs/source/en/guides/cli.md
+++ b/docs/source/en/guides/cli.md
@@ -114,15 +114,15 @@ You can also install the CLI using [Homebrew](https://brew.sh/):
 
 Check out the Homebrew huggingface page [here](https://formulae.brew.sh/formula/hf) for more details.
 
-### Upgrading
+### Updating
 
 To upgrade to the latest version, run:
 
 ```bash
->>> hf upgrade
+>>> hf update
 ```
 
-This detects how `hf` was installed (Homebrew, standalone installer, or pip) and runs the matching upgrade command.
+This detects how `hf` was installed (Homebrew, standalone installer, or pip) and runs the matching update command.
 
 By default, the CLI also prints a one-line yellow warning to stderr when a newer version is available on PyPI. To silence it (e.g. in offline CI), set `HF_HUB_DISABLE_UPDATE_CHECK=1`.
 
diff --git a/docs/source/en/package_reference/environment_variables.md b/docs/source/en/package_reference/environment_variables.md
index 8adad7ccd2..418f7516da 100644
--- a/docs/source/en/package_reference/environment_variables.md
+++ b/docs/source/en/package_reference/environment_variables.md
@@ -183,7 +183,7 @@ You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally dis
 
 ### HF_HUB_DISABLE_UPDATE_CHECK
 
-By default, the `hf` CLI checks PyPI for a newer release at startup (at most once every 24 hours) and prints a one-line yellow warning to stderr when one is available, suggesting `hf upgrade`. The check is already a no-op on dev and pre-release versions.
+By default, the `hf` CLI checks PyPI for a newer release at startup (at most once every 24 hours) and prints a one-line yellow warning to stderr when one is available, suggesting `hf update`. The check is already a no-op on dev and pre-release versions.
 
 Set `HF_HUB_DISABLE_UPDATE_CHECK=1` to skip the PyPI request and silence the warning entirely. Useful in offline CI environments or when you prefer a quieter shell output.
 
diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index f0916eeea1..8537930406 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -952,7 +952,7 @@ def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> Non
     """
     Check whether a newer version of a library is available on PyPI.
 
-    If a newer version is found, print a hint pointing at `hf upgrade`.
+    If a newer version is found, print a hint pointing at `hf update`.
 
     If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
     If `HF_HUB_DISABLE_UPDATE_CHECK` is set, the check is skipped entirely.
@@ -1008,7 +1008,7 @@ def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> No
     if update_command is not None:
         match library:
             case "huggingface_hub":
-                message += "\nTo update, run: hf upgrade"
+                message += "\nTo update, run: hf update"
             case _:
                 message += f"\nTo update, run: {' '.join(update_command)}"
     out.hint(message)
diff --git a/src/huggingface_hub/cli/skills.py b/src/huggingface_hub/cli/skills.py
index 1b8e9b2a19..2a8d26cc9d 100644
--- a/src/huggingface_hub/cli/skills.py
+++ b/src/huggingface_hub/cli/skills.py
@@ -101,7 +101,7 @@
 
 - Use `hf <command> --help` for full options, descriptions, usage, and real-world examples
 - Authenticate with `HF_TOKEN` env var (recommended) or with `--token`
-- Upgrade the CLI with `hf upgrade` (uses the correct command for the detected install method)
+- Update the CLI with `hf update` (uses the correct command for the detected install method)
 """
 
 CENTRAL_LOCAL = Path(".agents/skills")

From 09ed66443c146098fbe2624f7f3fbea6c609b106 Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 17:28:55 +0200
Subject: [PATCH 11/13] update

---
 src/huggingface_hub/cli/_cli_utils.py | 8 ++++----
 src/huggingface_hub/cli/system.py     | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/huggingface_hub/cli/_cli_utils.py b/src/huggingface_hub/cli/_cli_utils.py
index 8537930406..4b2bb54aa9 100644
--- a/src/huggingface_hub/cli/_cli_utils.py
+++ b/src/huggingface_hub/cli/_cli_utils.py
@@ -1014,16 +1014,16 @@ def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> No
     out.hint(message)
 
 
-def run_upgrade() -> int:
-    """Run the install-method-appropriate upgrade command for the `hf` CLI.
+def run_update() -> int:
+    """Run the install-method-appropriate update command for the `hf` CLI.
 
     Raises CLIError if the installation method can't be determined.
-    Returns the subprocess exit code on success/failure of the upgrade itself.
+    Returns the subprocess exit code on success/failure of the update itself.
     """
     cmd = _get_huggingface_hub_update_command()
     if cmd is None:
         raise CLIError(
-            "Cannot determine how to upgrade huggingface_hub (unknown installation method). Please upgrade manually."
+            "Cannot determine how to update huggingface_hub (unknown installation method). Please update manually."
         )
     return subprocess.call(cmd)
 
diff --git a/src/huggingface_hub/cli/system.py b/src/huggingface_hub/cli/system.py
index 92d6b862c2..a1b7ff3b6f 100644
--- a/src/huggingface_hub/cli/system.py
+++ b/src/huggingface_hub/cli/system.py
@@ -18,7 +18,7 @@
 from huggingface_hub import __version__
 
 from ..utils import dump_environment_info
-from ._cli_utils import run_upgrade
+from ._cli_utils import run_update
 from ._output import out
 
 
@@ -32,9 +32,9 @@ def version() -> None:
     print(__version__)
 
 
-def upgrade() -> None:
-    """Upgrade the `hf` CLI to the latest version."""
-    returncode = run_upgrade()
+def update() -> None:
+    """Update the `hf` CLI to the latest version."""
+    returncode = run_update()
     if returncode != 0:
         raise typer.Exit(code=returncode)
     out.hint(

From 050148e5586ff14be0f01a5edffce3e5807a195e Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 17:29:33 +0200
Subject: [PATCH 12/13] update

---
 docs/source/en/package_reference/cli.md | 8 ++++----
 src/huggingface_hub/cli/hf.py           | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/source/en/package_reference/cli.md b/docs/source/en/package_reference/cli.md
index a17236fc87..f6d250ad30 100644
--- a/docs/source/en/package_reference/cli.md
+++ b/docs/source/en/package_reference/cli.md
@@ -42,7 +42,7 @@ $ hf [OPTIONS] COMMAND [ARGS]...
 * `skills`: Manage skills for AI assistants.
 * `spaces`: Interact with spaces on the Hub.
 * `sync`: Sync files between local directory and a...
-* `upgrade`: Upgrade the `hf` CLI to the latest version.
+* `update`: Update the `hf` CLI to the latest version.
 * `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.
@@ -3764,14 +3764,14 @@ $ hf sync [OPTIONS] [SOURCE] [DEST]
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--help`: Show this message and exit.
 
-## `hf upgrade`
+## `hf update`
 
-Upgrade the `hf` CLI to the latest version.
+Update the `hf` CLI to the latest version.
 
 **Usage**:
 
 ```console
-$ hf upgrade [OPTIONS]
+$ hf update [OPTIONS]
 ```
 
 **Options**:
diff --git a/src/huggingface_hub/cli/hf.py b/src/huggingface_hub/cli/hf.py
index e35da70dba..cde7a41e55 100644
--- a/src/huggingface_hub/cli/hf.py
+++ b/src/huggingface_hub/cli/hf.py
@@ -42,7 +42,7 @@
 from huggingface_hub.cli.repos import repos_cli
 from huggingface_hub.cli.skills import skills_cli
 from huggingface_hub.cli.spaces import spaces_cli
-from huggingface_hub.cli.system import env, upgrade, version
+from huggingface_hub.cli.system import env, update, version
 from huggingface_hub.cli.upload import UPLOAD_EXAMPLES, upload
 from huggingface_hub.cli.upload_large_folder import UPLOAD_LARGE_FOLDER_EXAMPLES, upload_large_folder
 from huggingface_hub.cli.webhooks import webhooks_cli
@@ -80,7 +80,7 @@ def app_callback(
 app.command(examples=UPLOAD_LARGE_FOLDER_EXAMPLES)(upload_large_folder)
 
 app.command(topic="help")(env)
-app.command(topic="help")(upgrade)
+app.command(topic="help")(update)
 app.command(topic="help")(version)
 
 app.command(hidden=True)(lfs_enable_largefiles)

From 45a51cbca256f56387e9c2bb2e1f3b4c40b424c2 Mon Sep 17 00:00:00 2001
From: Lucain Pouget <lucainp@gmail.com>
Date: Wed, 22 Apr 2026 17:45:57 +0200
Subject: [PATCH 13/13] still annoyed

---
 docs/source/en/installation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md
index ad16b75822..0bc77723e5 100644
--- a/docs/source/en/installation.md
+++ b/docs/source/en/installation.md
@@ -118,7 +118,7 @@ On Windows:
 powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
 ```
 
-To upgrade an existing install, run `hf upgrade` — it detects how `hf` was installed (standalone installer, Homebrew, or pip) and runs the matching command.
+To upgrade an existing install, run `hf update` — it detects how `hf` was installed (standalone installer, Homebrew, or pip) and runs the matching command.
 
 ## Install with conda