[CLI] Add `hf spaces volumes` commands by Wauplin · Pull Request #4109 · huggingface/huggingface_hub

Wauplin · 2026-04-15T12:45:18Z

Mentioned by @davanstrien in huggingface/hub-docs#2381 (comment).

Summary

Adds hf spaces volumes ls/set/delete to manage Space volumes from the CLI. Reuses the existing -v/--volume syntax from hf repos create and hf jobs run.

Examples

$ hf spaces volumes ls Wauplin/test-volumes
TYPE    SOURCE                MOUNT_PATH READ_ONLY
------- --------------------- ---------- ---------
model   gpt2                  /data      ✔        
dataset badlogicgames/pi-mono /data2     ✔        
Hint: Use `hf spaces volumes set Wauplin/test-volumes -v hf://<repo_type>/<repo_id>:/<mount_path>` to set volumes for a Space.

$ hf spaces volumes set Wauplin/test-volumes -v hf://models/gpt2:/data-new
✓ Volumes set
  space_id: Wauplin/test-volumes
  volumes: ['hf://models/gpt2:/data-new']
Hint: Use `hf spaces volumes ls Wauplin/test-volumes` to list volumes for a Space.

$ hf spaces volumes ls Wauplin/test-volumes                               
TYPE  SOURCE MOUNT_PATH READ_ONLY
----- ------ ---------- ---------
model gpt2   /data-new  ✔        
Hint: Use `hf spaces volumes set Wauplin/test-volumes -v hf://<repo_type>/<repo_id>:/<mount_path>` to set volumes for a Space.

$ hf spaces volumes delete Wauplin/test-volumes
You are about to remove all volumes from Space 'Wauplin/test-volumes'. Proceed? [y/N]: 
Aborted!

$ hf spaces volumes delete Wauplin/test-volumes --yes
✓ Volumes deleted
  space_id: Wauplin/test-volumes
Hint: Use `hf spaces volumes set Wauplin/test-volumes -v hf://<repo_type>/<repo_id>:/<mount_path>` to set volumes for a Space.

$ hf spaces volumes ls Wauplin/test-volumes                               
No results found.
Hint: Use `hf spaces volumes set Wauplin/test-volumes -v hf://<repo_type>/<repo_id>:/<mount_path>` to set volumes for a Space.

🤖 Generated with Claude Code

Next I think we should also add commands for environment variables, secrets, sleep time and to request new hardware. If we agree on the syntax in this PR, adding the next ones should be straightforward.

Note

Medium Risk
Adds new CLI paths that can modify a Space’s mounted volumes (including destructive replace/delete), so mistakes could impact running Spaces but the change is largely additive and gated behind explicit user actions.

Overview
Adds a new hf spaces volumes CLI group with ls, set, and delete commands to manage Space volume mounts via space_info, set_space_volumes, and delete_space_volumes, including confirmation prompting for deletes.

Introduces Volume.to_hf_handle() to round-trip volumes back into the CLI hf://... syntax for output, and updates docs (manage-spaces.md and generated cli.md) to document the new commands and examples.

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

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) <[email protected]>

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

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

bot-ci-comment · 2026-04-15T12:58:02Z

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 · 2026-04-15T12:58:13Z

+        "hf spaces volumes ls username/my-space",
+    ],
+)
+def volumes_ls(


this is not the exact equivalent of an API method but it feels necessary / good to have for the CLI

hanouticelina

only a small suggestion to re-write the to_hf_handle helper, otherwise looks good to me!

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

davanstrien

Thanks!

One small suggestion for a follow-up, the VolumesOpt help text in _cli_utils.py says "Mount a volume", which makes it less clear that you can pass multiple -v flags. Changing to "Mount one or more volumes" could make it obvious to humans and agents?

davanstrien · 2026-04-15T14:47:44Z

Thanks!

One small suggestion for a follow-up, the VolumesOpt help text in _cli_utils.py says "Mount a volume", which makes it less clear that you can pass multiple -v flags. Changing to "Mount one or more volumes" could make it obvious to humans and agents?

#4113

huggingface-hub-bot · 2026-04-16T13:08:14Z

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

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

9f7a267

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) <[email protected]>

Wauplin added the highlight PR will be highlighted in the release notes. label Apr 15, 2026

Wauplin and others added 2 commits April 15, 2026 14:47

Merge branch 'main' into cli-spaces-volumes

3191c90

Add hints after volume commands

b46aa7b

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Wauplin mentioned this pull request Apr 15, 2026

Update Label Studio docs to recommend Storage Buckets for persistence huggingface/hub-docs#2381

Merged

Wauplin requested review from davanstrien and hanouticelina April 15, 2026 12:54

Wauplin marked this pull request as ready for review April 15, 2026 12:54

cursor Bot reviewed Apr 15, 2026

View reviewed changes

Comment thread src/huggingface_hub/_space_api.py Outdated

Wauplin commented Apr 15, 2026

View reviewed changes

fix hf handle

c24bda4

hanouticelina approved these changes Apr 15, 2026

View reviewed changes

Comment thread src/huggingface_hub/_space_api.py Outdated

Wauplin and others added 4 commits April 15, 2026 16:27

Update src/huggingface_hub/_space_api.py

2c36900

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

Merge branch 'main' into cli-spaces-volumes

e3abb83

code quality

10224c0

quality

8f2137d

Wauplin merged commit 6cace2b into main Apr 15, 2026
20 of 21 checks passed

Wauplin deleted the cli-spaces-volumes branch April 15, 2026 14:35

davanstrien approved these changes Apr 15, 2026

View reviewed changes

davanstrien mentioned this pull request Apr 29, 2026

[CLI] Add hf spaces secrets and variables subgroups #4170

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CLI] Add `hf spaces volumes` commands#4109

[CLI] Add `hf spaces volumes` commands#4109
Wauplin merged 8 commits intomainfrom
cli-spaces-volumes

Wauplin commented Apr 15, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

bot-ci-comment Bot commented Apr 15, 2026

Uh oh!

Wauplin Apr 15, 2026

Uh oh!

hanouticelina left a comment

Uh oh!

Uh oh!

Uh oh!

davanstrien left a comment

Uh oh!

davanstrien commented Apr 15, 2026 •

edited

Loading

Uh oh!

huggingface-hub-bot Bot commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Summary

Examples

Next I think we should also add commands for environment variables, secrets, sleep time and to request new hardware. If we agree on the syntax in this PR, adding the next ones should be straightforward.

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bot-ci-comment Bot commented Apr 15, 2026

Uh oh!

Wauplin Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

davanstrien left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Wauplin commented Apr 15, 2026 •

edited by cursor Bot

Loading

davanstrien commented Apr 15, 2026 •

edited

Loading