[CLI] Add hf spaces volumes commands (#4109)

* [CLI] Add `hf spaces volumes` commands (ls, set, delete)

Adds a `volumes` subcommand group under `hf spaces` to manage
Space volumes from the CLI, wrapping `set_space_volumes` and
`delete_space_volumes` API methods.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add hints after volume commands

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix hf handle

* Update src/huggingface_hub/_space_api.py

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

* code quality

* quality

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: célina <hanouticelina@gmail.com>

Author: 3 people

docs/source/en/guides/manage-spaces.md

@@ -283,6 +283,21 @@ To remove all volumes from your Space:
 > [!WARNING]
 > Setting volumes replaces any previously mounted volumes. To add a volume to an existing list, first read the current volumes from the runtime and include them in the new list.
 
+All volume operations are also available from the CLI:
+
+```bash
+# List current volumes
+hf spaces volumes ls username/my-space
+
+# Set (replace) volumes
+hf spaces volumes set username/my-space \
+    -v hf://models/username/my-model:/models \
+    -v hf://buckets/username/my-bucket:/data
+
+# Remove all volumes
+hf spaces volumes delete username/my-space
+```
+
 ## More advanced: temporarily upgrade your Space !
 
 Spaces allow for a lot of different use cases. Sometimes, you might want

docs/source/en/package_reference/cli.md

@@ -3404,6 +3404,7 @@ $ hf spaces [OPTIONS] COMMAND [ARGS]...
 * `info`: Get info about a space on the Hub.
 * `list`: List spaces on the Hub. [alias: ls]
 * `search`: Search spaces on the Hub using semantic...
+* `volumes`: Manage volumes for a Space on the Hub.
 
 ### `hf spaces dev-mode`
 
@@ -3582,6 +3583,114 @@ Learn more
   Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
 
 
+### `hf spaces volumes`
+
+Manage volumes for a Space on the Hub.
+
+**Usage**:
+
+```console
+$ hf spaces volumes [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `delete`: Remove all volumes from a Space.
+* `list`: List volumes mounted in a Space. [alias: ls]
+* `set`: Set (replace) volumes for a Space.
+
+#### `hf spaces volumes delete`
+
+Remove all volumes from a Space.
+
+**Usage**:
+
+```console
+$ hf spaces volumes delete [OPTIONS] SPACE_ID
+```
+
+**Arguments**:
+
+* `SPACE_ID`: The space ID (e.g. `username/repo-name`).  [required]
+
+**Options**:
+
+* `-y, --yes`: Answer Yes to prompt automatically.
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
+* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
+* `--help`: Show this message and exit.
+
+Examples
+  $ hf spaces volumes delete username/my-space
+  $ hf spaces volumes delete username/my-space --yes
+
+Learn more
+  Use `hf <command> --help` for more information about a command.
+  Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
+
+
+#### `hf spaces volumes list`
+
+List volumes mounted in a Space. [alias: ls]
+
+**Usage**:
+
+```console
+$ hf spaces volumes list [OPTIONS] SPACE_ID
+```
+
+**Arguments**:
+
+* `SPACE_ID`: The space ID (e.g. `username/repo-name`).  [required]
+
+**Options**:
+
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
+* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
+* `--help`: Show this message and exit.
+
+Examples
+  $ hf spaces volumes ls username/my-space
+
+Learn more
+  Use `hf <command> --help` for more information about a command.
+  Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
+
+
+#### `hf spaces volumes set`
+
+Set (replace) volumes for a Space.
+
+**Usage**:
+
+```console
+$ hf spaces volumes set [OPTIONS] SPACE_ID
+```
+
+**Arguments**:
+
+* `SPACE_ID`: The space ID (e.g. `username/repo-name`).  [required]
+
+**Options**:
+
+* `-v, --volume TEXT`: Mount a volume. Format: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. TYPE is one of: models, datasets, spaces, buckets. TYPE defaults to models if omitted. models, datasets and spaces are always mounted read-only. buckets are read+write by default.E.g. -v hf://gpt2:/data or -v hf://datasets/org/ds:/data or -v hf://buckets/org/b:/mnt:ro
+* `--format [agent|auto|human|json|quiet]`: Output format.  [default: auto]
+* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
+* `--help`: Show this message and exit.
+
+Examples
+  $ hf spaces volumes set username/my-space -v hf://models/username/my-model:/models
+  $ hf spaces volumes set username/my-space -v hf://buckets/username/my-bucket:/data -v hf://datasets/username/my-dataset:/datasets:ro
+
+Learn more
+  Use `hf <command> --help` for more information about a command.
+  Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
+
+
 ## `hf sync`
 
 Sync files between local directory and a bucket.

src/huggingface_hub/_space_api.py

@@ -161,6 +161,13 @@ def to_dict(self) -> dict:
             data["path"] = self.path
         return data
 
+    def to_hf_handle(self) -> str:
+        """Return the volume as an HF handle in the format expected by the CLI."""
+        path = f"/{self.path}" if self.path else ""
+        revision = f"@{self.revision}" if self.revision else ""
+        ro = {True: ":ro", False: ":rw", None: ""}.get(self.read_only, "")
+        return f"hf://{self.type}s/{self.source}{revision}{path}:{self.mount_path}{ro}"
+
 
 @dataclass
 class SpaceHotReloading:

src/huggingface_hub/cli/spaces.py

@@ -56,9 +56,11 @@
     RevisionOpt,
     SearchOpt,
     TokenOpt,
+    VolumesOpt,
     api_object_to_dict,
     get_hf_api,
     make_expand_properties_parser,
+    parse_volumes,
     typer_factory,
 )
 from ._output import OutputFormatWithAuto, out
@@ -81,6 +83,8 @@
 ]
 
 spaces_cli = typer_factory(help="Interact with spaces on the Hub.")
+volumes_cli = typer_factory(help="Manage volumes for a Space on the Hub.")
+spaces_cli.add_typer(volumes_cli, name="volumes")
 
 
 @spaces_cli.command(
@@ -482,3 +486,80 @@ def _editor_open(local_path: str) -> int | Literal["no-tty", "no-editor"]:
     command = [*shlex.split(editor_command), local_path]
     res = subprocess.run(command, start_new_session=True)
     return res.returncode
+
+
+@volumes_cli.command(
+    "list | ls",
+    examples=[
+        "hf spaces volumes ls username/my-space",
+    ],
+)
+def volumes_ls(
+    space_id: Annotated[str, typer.Argument(help="The space ID (e.g. `username/repo-name`).")],
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
+    token: TokenOpt = None,
+) -> None:
+    """List volumes mounted in a Space."""
+    api = get_hf_api(token=token)
+    info = api.space_info(space_id)
+    if info.runtime is None:
+        raise CLIError(f"Runtime not available for Space '{space_id}'.")
+    volumes = info.runtime.volumes or []
+    items = [api_object_to_dict(v) for v in volumes]
+    out.table(items)
+    out.hint(
+        f"Use `hf spaces volumes set {space_id} -v hf://<repo_type>/<repo_id>:/<mount_path>` to set volumes for a Space."
+    )
+
+
+@volumes_cli.command(
+    "set",
+    examples=[
+        "hf spaces volumes set username/my-space -v hf://models/username/my-model:/models",
+        "hf spaces volumes set username/my-space -v hf://buckets/username/my-bucket:/data -v hf://datasets/username/my-dataset:/datasets:ro",
+    ],
+)
+def volumes_set(
+    space_id: Annotated[str, typer.Argument(help="The space ID (e.g. `username/repo-name`).")],
+    volume: VolumesOpt = None,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
+    token: TokenOpt = None,
+) -> None:
+    """Set (replace) volumes for a Space."""
+    volumes = parse_volumes(volume)
+    if not volumes:
+        raise CLIError("At least one volume must be specified with -v/--volume.")
+    api = get_hf_api(token=token)
+    api.set_space_volumes(space_id, volumes=volumes)
+    out.result("Volumes set", space_id=space_id, volumes=[v.to_hf_handle() for v in volumes])
+    out.hint(f"Use `hf spaces volumes ls {space_id}` to list volumes for a Space.")
+
+
+@volumes_cli.command(
+    "delete",
+    examples=[
+        "hf spaces volumes delete username/my-space",
+        "hf spaces volumes delete username/my-space --yes",
+    ],
+)
+def volumes_delete(
+    space_id: Annotated[str, typer.Argument(help="The space ID (e.g. `username/repo-name`).")],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Answer Yes to prompt automatically.",
+        ),
+    ] = False,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
+    token: TokenOpt = None,
+) -> None:
+    """Remove all volumes from a Space."""
+    out.confirm(f"You are about to remove all volumes from Space '{space_id}'. Proceed?", yes=yes)
+    api = get_hf_api(token=token)
+    api.delete_space_volumes(space_id)
+    out.result("Volumes deleted", space_id=space_id)
+    out.hint(
+        f"Use `hf spaces volumes set {space_id} -v hf://<repo_type>/<repo_id>:/<mount_path>` to set volumes for a Space."
+    )