[CLI] Add `hf spaces ssh` by gary149 · Pull Request #4241 · huggingface/huggingface_hub

gary149 · 2026-05-20T09:08:57Z

Summary

Add hf spaces ssh <space_id> to SSH into a Space's Dev Mode container.

Features:

Detects whether Dev Mode is enabled via SpaceRuntime.dev_mode (new field, from API devMode).
If Dev Mode is off, prompts the user to enable it interactively (default to True), then waits until it's ready before connecting.
--auto flag skips the prompt and enables Dev Mode automatically.
--dry-run flag prints the ssh command instead of running it.
-i / --identity-file to forward a specific SSH key.

Other changes:

Updated hf spaces dev-mode output to mention hf spaces ssh.
Added dev_mode: bool attribute to SpaceRuntime.

Example:

✗ hf spaces ssh huggingface/tmp-dev-mode-test                     
Dev Mode is disabled on 'huggingface/tmp-dev-mode-test'. Enable it now? [Y/n]: 
app starting...
Dev mode ready!
Running `ssh huggingface-tmp-dev-mode-test@ssh.hf.space`
root@r-huggingface-tmp-dev-mode-test-2msg752d-86560-vhqp4:/app# ls

Usage:

# Basic usage
$ hf spaces ssh username/my-space

# Print the command without running it
$ hf spaces ssh username/my-space --dry-run
ssh username-my-space@ssh.hf.space

# Auto-enable dev mode + SSH
$ hf spaces ssh username/my-space --auto

# With a specific SSH key
$ hf spaces ssh username/my-space -i ~/.ssh/id_ed25519

🤖 Generated with Claude Code

Note

Low Risk
Low risk: primarily adds a new CLI entrypoint plus small refactoring and a new SpaceRuntime.dev_mode field; behavior changes are limited to Dev Mode workflows and interactive confirmations.

Overview
Adds hf spaces ssh to open an SSH session into a Space’s Dev Mode container, supporting --auto (enable Dev Mode without prompting), --dry-run (print the ssh command), and -i/--identity-file (forward an SSH key).

Extends SpaceRuntime with a dev_mode flag sourced from the API (devMode), refactors hf spaces dev-mode to reuse a shared “wait until Dev Mode is ready” helper, and updates CLI/docs reference pages to document the new SSH workflow. Also generalizes out.confirm() so commands can customize the “skip confirmation” flag text (used to point users to --auto for this command).

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

bot-ci-comment · 2026-05-20T09:15:31Z

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.

- Fix dev mode detection: use `SpaceRuntime.dev_mode` (from API `devMode` field) instead of checking `subdomain` presence. - Rename `--print` to `--dry-run` (follows gcloud/git/make convention). - Add `--auto` flag to enable Dev Mode without prompting. - If dev mode is off, prompt user to enable it (interactive confirm). - Extract `_wait_for_dev_mode` helper shared by `dev-mode` and `ssh`. - Remove unnecessary `FileNotFoundError` catch on `ssh` subprocess. - Mention `hf spaces ssh` in `dev-mode` output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor · 2026-05-21T10:36:48Z

+    cmd = ["ssh"]
+    if identity_file is not None:
+        cmd += ["-i", str(identity_file)]
+    cmd.append(f"{info.subdomain}@ssh.hf.space")


SSH attempted without waiting for space to be running

Medium Severity

When dev mode is already enabled (info.runtime.dev_mode is True) but the space is still in an intermediate stage (BUILDING, APP_STARTING, etc.), the code skips the _wait_for_dev_mode call and immediately attempts SSH. This happens if a user enables dev mode through the web UI or another CLI invocation and then quickly runs hf spaces ssh before the container is ready. The SSH connection will fail because the container isn't accepting connections yet. The wait logic only executes in the branch where dev mode was just enabled by this command.

^{Reviewed by Cursor Bugbot for commit 9e49757. Configure here.}

no it's fine

cursor

Cursor Bugbot has reviewed your changes using default mode and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c32ba09. Configure here.}

Wauplin · 2026-05-21T12:00:14Z

Tested and works well on https://huggingface.co/spaces/huggingface/tmp-dev-mode-test

✗ hf spaces ssh huggingface/tmp-dev-mode-test                     
Dev Mode is disabled on 'huggingface/tmp-dev-mode-test'. Enable it now? [Y/n]: 
app starting...
Dev mode ready!
Running `ssh huggingface-tmp-dev-mode-test@ssh.hf.space`
root@r-huggingface-tmp-dev-mode-test-2msg752d-86560-vhqp4:/app# ls

✗ hf spaces ssh huggingface/tmp-dev-mode-test
Running `ssh huggingface-tmp-dev-mode-test@ssh.hf.space`
root@r-huggingface-tmp-dev-mode-test-2msg752d-86560-vhqp4:/app# pwd
/app
root@r-huggingface-tmp-dev-mode-test-2msg752d-86560-vhqp4:/app# 
exit
Connection to ssh.hf.space closed.

hanouticelina

looks good!

huggingface-hub-bot · 2026-05-28T15:12:30Z

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

Add a CLI shortcut to the Dev Mode SSH section: `hf spaces ssh` resolves the Space subdomain and opens the session for you, with `--dry-run` and `-i` examples plus an `--auto` note. Complements the existing manual `ssh <subdomain>@ssh.hf.space` instructions; the existing "register your SSH key" line covers the prerequisite for both paths. Added in huggingface_hub v1.17.0 (huggingface/huggingface_hub#4241). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a CLI shortcut to the Dev Mode SSH section: `hf spaces ssh` resolves the Space subdomain and opens the session for you, with `--dry-run` and `-i` examples plus an `--auto` note. Complements the existing manual `ssh <subdomain>@ssh.hf.space` instructions; the existing "register your SSH key" line covers the prerequisite for both paths. Added in huggingface_hub v1.17.0 (huggingface/huggingface_hub#4241). Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

[CLI] Add hf spaces ssh <space_id>

b4c7350

Wauplin changed the title ~~[CLI] Add hf spaces ssh <space_id>~~ [CLI] Add hf spaces ssh May 21, 2026

Merge branch 'main' into cli/spaces-ssh

9e49757

cursor Bot reviewed May 21, 2026

View reviewed changes

Wauplin added 2 commits May 21, 2026 12:55

fix quality

bfdebfb

Merge branch 'main' into cli/spaces-ssh

a797d17

cursor Bot reviewed May 21, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/spaces.py

fixes

c32ba09

cursor Bot reviewed May 21, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/spaces.py Outdated

add confirm param

bbad132

better

bb12de1

Wauplin approved these changes May 21, 2026

View reviewed changes

Wauplin marked this pull request as ready for review May 21, 2026 12:30

Wauplin requested a review from hanouticelina May 21, 2026 12:30

docs

db5beec

hanouticelina approved these changes May 21, 2026

View reviewed changes

hanouticelina merged commit 20eece8 into main May 21, 2026
21 checks passed

hanouticelina deleted the cli/spaces-ssh branch May 21, 2026 13:49

davanstrien mentioned this pull request Jun 4, 2026

Document hf spaces ssh in the Spaces Dev Mode guide huggingface/hub-docs#2534

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CLI] Add `hf spaces ssh`#4241

[CLI] Add `hf spaces ssh`#4241
hanouticelina merged 9 commits into
mainfrom
cli/spaces-ssh

gary149 commented May 20, 2026 •

edited by cursor Bot

Loading

Uh oh!

bot-ci-comment Bot commented May 20, 2026

Uh oh!

cursor Bot May 21, 2026

Uh oh!

Wauplin May 21, 2026

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Wauplin commented May 21, 2026 •

edited

Loading

Uh oh!

hanouticelina left a comment

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gary149 commented May 20, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

bot-ci-comment Bot commented May 20, 2026

Uh oh!

cursor Bot May 21, 2026

Choose a reason for hiding this comment

SSH attempted without waiting for space to be running

Uh oh!

Wauplin May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Wauplin commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

huggingface-hub-bot Bot commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gary149 commented May 20, 2026 •

edited by cursor Bot

Loading

Wauplin commented May 21, 2026 •

edited

Loading