[CLI] Add spaces lifecycle commands: pause, restart, sleep

[davanstrien]

Summary

Wraps three existing HfApi methods so Spaces lifecycle is controllable from the CLI:

• hf spaces pause <id> → pause_space
• hf spaces restart <id> [--factory-reboot] → restart_space
• hf spaces sleep <id> --seconds N → set_space_sleep_time

CLI examples

$ hf spaces pause --help
Usage: hf spaces pause [OPTIONS] SPACE_ID

  Pause a Space.

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.
  -h, --help                      Show this message and exit.

Examples
  $ hf spaces pause username/my-space
  $ hf spaces pause username/my-space --yes

hf spaces restart --help and hf spaces sleep --help follow the same shape (with --factory-reboot and --seconds respectively).

Tests pass:

$ pytest tests/test_cli.py -k TestSpacesLifecycleCommands
tests/test_cli.py::TestSpacesLifecycleCommands::test_pause PASSED
tests/test_cli.py::TestSpacesLifecycleCommands::test_restart_factory_reboot PASSED
tests/test_cli.py::TestSpacesLifecycleCommands::test_sleep PASSED
3 passed in 0.40s

Live smoke test against a real Space pending — will add output before un-drafting.

Discussion point: confirmation prompts

pause and restart ship with an out.confirm() prompt + -y/--yes flag, mirroring volumes delete. This is a deliberate divergence from the established CLI rule (verified across repos.py, buckets.py, spaces.py, auth.py):

confirm = deletion, no confirm = state change

By that rule, pause/restart should not prompt — they parallel dev_mode --stop (which tears down a running container without asking).

Reasoning for diverging here: pausing/restarting wipes ephemeral storage on the Space's container. Users who haven't mounted a Volume can lose unsaved data. The same is true of the dashboard buttons, but a CLI invocation is easier to script/automate, which raises the blast radius.

sleep does not prompt (it's a config update, no container teardown).

Happy to remove the prompts if you'd rather stay consistent with the rest of the CLI — let me know.

Notes

• space_id argument shape, -y/--yes shape (Answer Yes to prompt automatically.), and out.result(...) + out.hint(...) output style all match existing spaces.py patterns verbatim.
• Docs guide at cli.md adds three terse subsections matching the existing tone (frame pause around billing, link to canonical docs for sleep).
• package_reference/cli.md regenerated by make style (do not edit by hand).
• Cross-linking from hub-docs/spaces-gpus.md (#pause, #sleep-time) is a separate follow-up PR.

---

Note

Medium Risk
Adds new hf spaces lifecycle commands that trigger remote runtime actions (pause/restart/factory reboot and sleep-time changes), so misuse could interrupt running Spaces or discard ephemeral data.

Overview
Adds new Spaces lifecycle controls to the hf CLI: hf spaces pause and hf spaces restart (optionally --factory-reboot) plus hf spaces settings --sleep-time for updating a Space’s sleep timeout.

Documentation is updated to describe these commands and warn that pausing/restarting tears down the container (ephemeral filesystem is lost), and the autogenerated CLI reference now includes the new subcommands and options.

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

[bot-ci-comment]

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.

[davanstrien]

Ran smoke tests locally now

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

[Wauplin]

hf spaces sleep <id> --seconds N

I find this syntax quite misleading. I would expect a hf spaces sleep <id> to put the Space to sleep, i.e. exactly what hf spaces pause is doing. I would suggest either hf spaces settings <id> --sleep-time <SECONDS>, similar to the current hf repos settings <id> ... or hf spaces --set-sleep-time. Slight preference for the former for explicitness even though it's not consistent with the HfApi methods. Later we might do hf spaces settings <id> --hardware ... as well?

Otherwise hf spaces --set-sleep-time / hf spaces --set-hardware is also fine to be consistent with the HfApi calls. Happy to get some suggestions on this @davanstrien @hanouticelina

Discussion point: confirmation prompts

Good point discussing this. I would tend to think confirmation prompt is a bit too much for a pause/restart since by nature Space storage is ephemeral so we are not really deleting "hard storage". I would just go yolo on that

[hanouticelina]

I have a preference for hf spaces settings <id> --sleep-time <SECONDS> as well

[davanstrien]

• Renamed sleep --seconds → settings --sleep-time. Went with the settings shape since it mirrors hf repos settings and gives --hardware etc. a home later without new top-level verbs.
• Dropped confirms on pause/restart
• For secrets/variables later it might make sense to keep them as nested subgroups (hf spaces secrets set/rm/ls) like volumes — i.e. settings for single-value attributes, subgroups for keyed collections?

[Wauplin]

For secrets/variables later it might make sense to keep them as nested subgroups (hf spaces secrets set/rm/ls) like volumes — i.e. settings for single-value attributes, subgroups for keyed collections?

Yes, agree on this as well 👍

[Wauplin]

Thank you!

[hanouticelina]

Thanks!

[huggingface-hub-bot]

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