Add visibility parameter to HfApi repo create/update/duplicate methods (#3951)

* Add visibility to repo visibility APIs

Co-authored-by: célina <hanouticelina@users.noreply.github.com>

* Add visibility options to repo CLI

Co-authored-by: célina <hanouticelina@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: célina <hanouticelina@gmail.com>

* review suggestions

* hid private param

* add hidden --private --public --protected

* remove --visibility option

* update tests and docs

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: célina <hanouticelina@users.noreply.github.com>

Author: hanouticelina

docs/source/en/package_reference/cli.md

@@ -2916,6 +2916,8 @@ $ hf repos create [OPTIONS] REPO_ID
 * `--type, --repo-type [model|dataset|space]`: The type of repository (model, dataset, or space).  [default: model]
 * `--space-sdk TEXT`: Hugging Face Spaces SDK type. Required when --type is set to 'space'.
 * `--private / --no-private`: Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.
+* `--public`: Whether to make the repo public. Ignored if the repo already exists.
+* `--protected`: Whether to make the Space protected (Spaces only). Ignored if the repo already exists.
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--exist-ok / --no-exist-ok`: Do not raise an error if repo already exists.  [default: no-exist-ok]
 * `--resource-group-id TEXT`: Resource group in which to create the repo. Resource groups is only available for Enterprise Hub organizations.
@@ -2931,7 +2933,7 @@ $ hf repos create [OPTIONS] REPO_ID
 Examples
   $ hf repos create my-model
   $ hf repos create my-dataset --repo-type dataset --private
-  $ hf repos create my-space --type space --space-sdk gradio --flavor t4-medium --secrets HF_TOKEN -e THEME=dark
+  $ hf repos create my-space --type space --space-sdk gradio --flavor t4-medium --secrets HF_TOKEN -e THEME=dark --protected
 
 Learn more
   Use `hf <command> --help` for more information about a command.
@@ -3021,6 +3023,8 @@ $ hf repos duplicate [OPTIONS] FROM_ID [TO_ID]
 
 * `--type, --repo-type [model|dataset|space]`: The type of repository (model, dataset, or space).  [default: model]
 * `--private / --no-private`: Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.
+* `--public`: Whether to make the repo public. Ignored if the repo already exists.
+* `--protected`: Whether to make the Space protected (Spaces only). Ignored if the repo already exists.
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--exist-ok / --no-exist-ok`: Do not raise an error if repo already exists.  [default: no-exist-ok]
 * `--flavor TEXT`: Space hardware flavor (e.g. 'cpu-basic', 't4-medium', 'l4x4'). Only for Spaces.
@@ -3087,14 +3091,17 @@ $ hf repos settings [OPTIONS] REPO_ID
 **Options**:
 
 * `--gated [auto|manual|false]`: The gated status for the repository.
-* `--private / --no-private`: Whether the repository should be private.
+* `--private / --no-private`: Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.
+* `--public`: Whether to make the repo public. Ignored if the repo already exists.
+* `--protected`: Whether to make the Space protected (Spaces only). Ignored if the repo already exists.
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
 * `--type, --repo-type [model|dataset|space]`: The type of repository (model, dataset, or space).  [default: model]
 * `--help`: Show this message and exit.
 
 Examples
   $ hf repos settings my-model --private
   $ hf repos settings my-model --gated auto
+  $ hf repos settings my-space --repo-type space --protected
 
 Learn more
   Use `hf <command> --help` for more information about a command.

src/huggingface_hub/cli/repos.py

@@ -75,6 +75,21 @@ class GatedChoices(str, enum.Enum):
     false = "false"
 
 
+PublicOpt = Annotated[
+    Optional[bool],
+    typer.Option(
+        "--public",
+        help="Whether to make the repo public. Ignored if the repo already exists.",
+    ),
+]
+
+ProtectedOpt = Annotated[
+    Optional[bool],
+    typer.Option(
+        "--protected",
+        help="Whether to make the Space protected (Spaces only). Ignored if the repo already exists.",
+    ),
+]
 SpaceHardwareOpt = Annotated[
     Optional[str],
     typer.Option(
@@ -105,7 +120,7 @@ class GatedChoices(str, enum.Enum):
     examples=[
         "hf repos create my-model",
         "hf repos create my-dataset --repo-type dataset --private",
-        "hf repos create my-space --type space --space-sdk gradio --flavor t4-medium --secrets HF_TOKEN -e THEME=dark",
+        "hf repos create my-space --type space --space-sdk gradio --flavor t4-medium --secrets HF_TOKEN -e THEME=dark --protected",
     ],
 )
 def repo_create(
@@ -118,6 +133,8 @@ def repo_create(
         ),
     ] = None,
     private: PrivateOpt = None,
+    public: PublicOpt = None,
+    protected: ProtectedOpt = None,
     token: TokenOpt = None,
     exist_ok: Annotated[
         bool,
@@ -144,7 +161,7 @@ def repo_create(
     repo_url = api.create_repo(
         repo_id=repo_id,
         repo_type=repo_type.value,
-        private=private,
+        visibility="private" if private else "public" if public else "protected" if protected else None,  # type: ignore [arg-type]
         token=token,
         exist_ok=exist_ok,
         resource_group_id=resource_group_id,
@@ -176,6 +193,8 @@ def repo_duplicate(
     ] = None,
     repo_type: RepoTypeOpt = RepoType.model,
     private: PrivateOpt = None,
+    public: PublicOpt = None,
+    protected: ProtectedOpt = None,
     token: TokenOpt = None,
     exist_ok: Annotated[
         bool,
@@ -197,7 +216,7 @@ def repo_duplicate(
         from_id=from_id,
         to_id=to_id,
         repo_type=repo_type.value,
-        private=private,
+        visibility="private" if private else "public" if public else "protected" if protected else None,  # type: ignore [arg-type]
         token=token,
         exist_ok=exist_ok,
         space_hardware=hardware,  # type: ignore[arg-type]
@@ -254,6 +273,7 @@ def repo_move(
     examples=[
         "hf repos settings my-model --private",
         "hf repos settings my-model --gated auto",
+        "hf repos settings my-space --repo-type space --protected",
     ],
 )
 def repo_settings(
@@ -264,12 +284,9 @@ def repo_settings(
             help="The gated status for the repository.",
         ),
     ] = None,
-    private: Annotated[
-        Optional[bool],
-        typer.Option(
-            help="Whether the repository should be private.",
-        ),
-    ] = None,
+    private: PrivateOpt = None,
+    public: PublicOpt = None,
+    protected: ProtectedOpt = None,
     token: TokenOpt = None,
     repo_type: RepoTypeOpt = RepoType.model,
 ) -> None:
@@ -278,7 +295,7 @@ def repo_settings(
     api.update_repo_settings(
         repo_id=repo_id,
         gated=(gated.value if gated else None),  # type: ignore [arg-type]
-        private=private,
+        visibility="private" if private else "public" if public else "protected" if protected else None,  # type: ignore [arg-type]
         repo_type=repo_type.value,
     )
     print(f"Successfully updated the settings of {ANSI.bold(repo_id)} on the Hub.")

src/huggingface_hub/hf_api.py

@@ -150,6 +150,7 @@
 R = TypeVar("R")  # Return type
 CollectionItemType_T = Literal["model", "dataset", "space", "paper", "collection"]
 CollectionSort_T = Literal["lastModified", "trending", "upvotes"]
+RepoVisibility_T = Literal["public", "private", "protected"]
 
 ExpandModelProperty_T = Literal[
     "author",
@@ -249,10 +250,28 @@
 _BUCKET_PATHS_INFO_BATCH_SIZE = 1000
 _BUCKET_BATCH_ADD_CHUNK_SIZE = 100
 _BUCKET_BATCH_DELETE_CHUNK_SIZE = 1000
-
 logger = logging.get_logger(__name__)
 
 
+def _resolve_repo_visibility(
+    *,
+    private: Optional[bool],
+    visibility: Optional[RepoVisibility_T],
+    repo_type: Optional[str],
+) -> Optional[RepoVisibility_T]:
+    if private is not None and visibility is not None:
+        raise ValueError("Received both `private` and `visibility` arguments. Please provide only one of them.")
+
+    if visibility is None:
+        if private is None:
+            return None
+        return "private" if private else "public"
+
+    if visibility == "protected" and repo_type != constants.REPO_TYPE_SPACE:
+        raise ValueError("Only Spaces can be 'protected'. Please set visibility to 'public' or 'private'.")
+    return visibility
+
+
 def repo_type_and_id_from_hf_id(hf_id: str, hub_url: Optional[str] = None) -> tuple[Optional[str], Optional[str], str]:
     """
     Returns the repo type and ID from a huggingface.co URL linking to a
@@ -4108,6 +4127,7 @@ def create_repo(
         *,
         token: Union[str, bool, None] = None,
         private: Optional[bool] = None,
+        visibility: Optional[RepoVisibility_T] = None,
         repo_type: Optional[str] = None,
         exist_ok: bool = False,
         resource_group_id: Optional[str] = None,
@@ -4130,7 +4150,11 @@ def create_repo(
                 https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
                 To disable authentication, pass `False`.
             private (`bool`, *optional*):
-                Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists.
+                Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists. Cannot be passed together with `visibility`.
+            visibility (`Literal["public", "private", "protected"]`, *optional*):
+                Visibility of the repo. Can be `"public"` or `"private"`, or `"protected"` for Spaces. If `None`
+                (default), the repo will be public unless the organization's default is private. This value is ignored
+                if the repo already exists.
             repo_type (`str`, *optional*):
                 Set to `"dataset"` or `"space"` if uploading to a dataset or
                 space, `None` or `"model"` if uploading to a model. Default is
@@ -4171,9 +4195,11 @@ def create_repo(
         if repo_type not in constants.REPO_TYPES:
             raise ValueError("Invalid repo type")
 
+        resolved_visibility = _resolve_repo_visibility(private=private, visibility=visibility, repo_type=repo_type)
+
         json: dict[str, Any] = {"name": name, "organization": organization}
-        if private is not None:
-            json["private"] = private
+        if resolved_visibility is not None:
+            json["visibility"] = resolved_visibility
         if repo_type is not None:
             json["type"] = repo_type
         if repo_type == "space":
@@ -4303,14 +4329,15 @@ def update_repo_settings(
         *,
         gated: Optional[Literal["auto", "manual", False]] = None,
         private: Optional[bool] = None,
+        visibility: Optional[RepoVisibility_T] = None,
         token: Union[str, bool, None] = None,
         repo_type: Optional[str] = None,
     ) -> None:
         """
         Update the settings of a repository, including gated access and visibility.
 
         To give more control over how repos are used, the Hub allows repo authors to enable
-        access requests for their repos, and also to set the visibility of the repo to private.
+        access requests for their repos, and also to change the visibility of the repo.
 
         Args:
             repo_id (`str`):
@@ -4321,7 +4348,9 @@ def update_repo_settings(
                 * "manual": The repository is gated, and access requests require manual approval.
                 * False : The repository is not gated, and anyone can access it.
             private (`bool`, *optional*):
-                Whether the repository should be private.
+                Whether the repository should be private. Cannot be passed together with `visibility`.
+            visibility (`Literal["public", "private", "protected"]`, *optional*):
+                Visibility of the repository. Can be `"public"` or `"private"`, or `"protected"` for Spaces.
             token (`Union[str, bool, None]`, *optional*):
                 A valid user access token (string). Defaults to the locally saved token,
                 which is the recommended method for authentication (see
@@ -4347,6 +4376,8 @@ def update_repo_settings(
         if repo_type is None:
             repo_type = constants.REPO_TYPE_MODEL  # default repo type
 
+        resolved_visibility = _resolve_repo_visibility(private=private, visibility=visibility, repo_type=repo_type)
+
         # Prepare the JSON payload for the PUT request
         payload: dict = {}
 
@@ -4355,8 +4386,8 @@ def update_repo_settings(
                 raise ValueError(f"Invalid gated status, must be one of 'auto', 'manual', or False. Got '{gated}'.")
             payload["gated"] = gated
 
-        if private is not None:
-            payload["private"] = private
+        if resolved_visibility is not None:
+            payload["visibility"] = resolved_visibility
 
         if len(payload) == 0:
             raise ValueError("At least one setting must be updated.")
@@ -7776,6 +7807,7 @@ def duplicate_repo(
         *,
         repo_type: Optional[str] = None,
         private: Optional[bool] = None,
+        visibility: Optional[RepoVisibility_T] = None,
         token: Union[bool, str, None] = None,
         exist_ok: bool = False,
         space_hardware: Optional[SpaceHardware] = None,
@@ -7800,7 +7832,10 @@ def duplicate_repo(
                 `None` or `"model"` if duplicating a model. Default is `None`.
             private (`bool`, *optional*):
                 Whether the new repo should be private or not. Defaults to the same
-                privacy as the original repo.
+                privacy as the original repo. Cannot be passed together with `visibility`.
+            visibility (`Literal["public", "private", "protected"]`, *optional*):
+                Visibility of the new repo. Can be `"public"` or `"private"`, or `"protected"` for Spaces. Defaults
+                to the same visibility as the original repo.
             token (`bool` or `str`, *optional*):
                 A valid user access token (string). Defaults to the locally saved
                 token, which is the recommended method for authentication (see
@@ -7862,6 +7897,8 @@ def duplicate_repo(
         if repo_type not in constants.REPO_TYPES:
             raise ValueError("Invalid repo type")
 
+        resolved_visibility = _resolve_repo_visibility(private=private, visibility=visibility, repo_type=repo_type)
+
         # Map repo_type to API path segment
         api_prefix = {
             None: "models",
@@ -7883,8 +7920,8 @@ def duplicate_repo(
 
         payload: dict[str, Any] = {"repository": f"{to_namespace}/{to_repo_name}"}
 
-        if private is not None:
-            payload["private"] = private
+        if resolved_visibility is not None:
+            payload["visibility"] = resolved_visibility
 
         # Space-specific options
         function_args = [
@@ -7935,6 +7972,7 @@ def duplicate_space(
         to_id: Optional[str] = None,
         *,
         private: Optional[bool] = None,
+        visibility: Optional[RepoVisibility_T] = None,
         token: Union[bool, str, None] = None,
         exist_ok: bool = False,
         hardware: Optional[SpaceHardware] = None,
@@ -7955,7 +7993,10 @@ def duplicate_space(
                 ID of the new Space. Example: `"dog/CLIP-Interrogator"`. If not provided, the new Space will have the same
                 name as the original Space, but in your account.
             private (`bool`, *optional*):
-                Whether the new Space should be private or not. Defaults to the same privacy as the original Space.
+                Whether the new Space should be private or not. Defaults to the same privacy as the original Space. Cannot be passed together with `visibility`.
+            visibility (`Literal["public", "private", "protected"]`, *optional*):
+                Visibility of the new Space. Can be `"public"`, `"private"`, or `"protected"`. Defaults to the same
+                visibility as the original Space.
             token (`bool` or `str`, *optional*):
                 A valid user access token (string). Defaults to the locally saved
                 token, which is the recommended method for authentication (see
@@ -7999,7 +8040,7 @@ def duplicate_space(
         RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)
 
         # Can set custom destination id and visibility flag.
-        >>> duplicate_space("multimodalart/dreambooth-training", to_id="my-dreambooth", private=True)
+        >>> duplicate_space("multimodalart/dreambooth-training", to_id="my-dreambooth", visibility="private")
         RepoUrl('https://huggingface.co/spaces/nateraw/my-dreambooth',...)
         ```
 
@@ -8013,6 +8054,7 @@ def duplicate_space(
             from_id=from_id,
             repo_type="space",
             private=private,
+            visibility=visibility,
             token=token,
             exist_ok=exist_ok,
             space_hardware=hardware,