[CLI] Add `hf spaces search` command with semantic search by Wauplin · Pull Request #4094 · huggingface/huggingface_hub

Wauplin · 2026-04-13T13:52:42Z

This PR introduces search_spaces() to perform semantic search of Spaces on the Hub (this endpoint: https://huggingface.co/api/spaces/semantic-search?q=generate+image)

Also adds hf spaces search <query> CLI command.

`hf spaces search "generate image"`

ID                                  TITLE                       SDK    LIKES STAGE   CATEGORY         SCORE
----------------------------------- --------------------------- ------ ----- ------- ---------------- -----
mrfakename/Z-Image-Turbo            Z Image Turbo               gradio 2867  RUNNING Image Generation 0.9  
r3gm/wan2-2-fp8da-aoti-preview      Wan2.2 14B Preview          gradio 2016  RUNNING Video Generation 0.81 
black-forest-labs/FLUX.2-dev        FLUX.2 [dev]                gradio 825   RUNNING Image Generation 0.77 
black-forest-labs/FLUX.2-klein-9B   FLUX.2 [Klein] 9B           gradio 739   RUNNING Image Generation 0.76 
Kwai-Kolors/Kolors-Virtual-Try-On   Kolors Virtual Try-On       gradio 10028 RUNNING Image Editing    0.75 
multimodalart/nano-banana           Nano Banana PRO             gradio 663   RUNNING Image Generation 0.75 
microsoft/TRELLIS.2                 TRELLIS.2                   gradio 1394  RUNNING 3D Modeling      0.74 
black-forest-labs/FLUX.1-dev        FLUX.1 [dev]                gradio 9427  RUNNING Image Generation 0.74 
r3gm/wan2-2-fp8da-aoti-preview2     Wan2.2 14B Fast Preview     gradio 667   RUNNING Video Generation 0.74 
prithivMLmods/FireRed-Image-Edit... FireRed Image Edit 1.0 Fast gradio 803   RUNNING Image Editing    0.73 
Hint: Use --description to show AI-generated descriptions.

`hf spaces search "chatbot" --sdk gradio --limit 2`

ID                      TITLE   SDK    LIKES STAGE   CATEGORY SCORE
----------------------- ------- ------ ----- ------- -------- -----
BarBar288/Chatbot       Chatbot gradio 4     RUNNING Other    0.5  
Pankajpandey221/Chatbot Chatbot gradio 2     RUNNING Chatbots 0.47 
Hint: Use --description to show AI-generated descriptions.

`hf spaces search "remove background from photo" --description --json --limit 1| jq`

[
  {
    "id": "briaai/BRIA-RMBG-1.4",
    "title": "BRIA RMBG 1.4",
    "sdk": "gradio",
    "likes": 871,
    "stage": "RUNNING",
    "category": "Image Editing",
    "score": 0.87,
    "description": "Remove background from your photos instantly"
  }
]

🤖 Generated with Claude Code

Note

Low Risk
Additive API/CLI and documentation changes with minimal impact on existing behavior; main risk is correctness/compatibility with the new /api/spaces/semantic-search response shape.

Overview
Adds a new HfApi.search_spaces method (and top-level search_spaces) that calls the Hub’s /api/spaces/semantic-search endpoint and returns structured SpaceSearchResult objects.

Introduces a new hf spaces search CLI command that renders search results (optionally including AI-generated descriptions) and updates docs/API reference to document the new search capability, with a basic test covering the new API.

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

Add `search_spaces()` method to `HfApi` and `hf spaces search <query>` CLI command that calls the Hub's semantic search API (`/api/spaces/semantic-search`). Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

bot-ci-comment · 2026-04-13T13:58:39Z

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.

hanouticelina

thanks! i left a comment about the missing exports (search_spaces = api.search_spaces in hf_api.py + __init__.py) otherwise looks good to me!

hanouticelina · 2026-04-13T16:42:54Z

+        query: str,
+        *,
+        filter: str | Iterable[str] | None = None,
+        sdk: str | list[str] | None = None,


Suggested change

sdk: str | list[str] | None = None,

sdk: str | None = None,

updated in b7c430f to allow multiple sdks in CLI (instead of forbidding it in API).

Tested and works as expected:

✗ hf spaces search "image generation" --sdk static ID TITLE SDK LIKES STAGE CATEGORY SCORE -------------------------- ----------------------------------- ------ ----- ------- ------------- ----- ArtelTaleb/8view-ai-studio 8view AI — 3D Topology Reference... static 5 RUNNING 3D Modeling 0.8 byliang/SECA SECA: Semantically Equivalent an... static 3 RUNNING Text Analysis 0.04 Hint: Use --description to show AI-generated descriptions. ✗ hf spaces search "image generation" --sdk docker ID TITLE SDK LIKES STAGE CATEGORY SCORE ----------------------------- --------------------- ------ ----- ------- ---------------- ----- gdTharusha/3D-Modle-Generator TripoSR docker 51 RUNNING 3D Modeling 0.85 jbilcke-hf/ai-comic-factory AI Comic Factory docker 11024 RUNNING Image Generation 0.73 lsmpp/openpose OpenPose Preprocessor docker 6 RUNNING Image Processing 0.63 lokesh180340026/Comfy-UI Comfy UI docker 5 RUNNING Image Generation 0.22 Hint: Use --description to show AI-generated descriptions. ✗ hf spaces search "image generation" --sdk docker --sdk static ID TITLE SDK LIKES STAGE CATEGORY SCORE ----------------------------- ----------------------------------- ------ ----- ------- ---------------- ----- gdTharusha/3D-Modle-Generator TripoSR docker 51 RUNNING 3D Modeling 0.85 lokesh180340026/Comfy-UI Comfy UI docker 5 RUNNING Image Generation 0.79 jbilcke-hf/ai-comic-factory AI Comic Factory docker 11024 RUNNING Image Generation 0.77 lsmpp/openpose OpenPose Preprocessor docker 6 RUNNING Image Processing 0.66 ArtelTaleb/8view-ai-studio 8view AI — 3D Topology Reference... static 5 RUNNING 3D Modeling 0.66 byliang/SECA SECA: Semantically Equivalent an... static 3 RUNNING Text Analysis 0.04 Hint: Use --description to show AI-generated descriptions.

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

cursor · 2026-04-13T20:13:20Z

+def spaces_search(
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    filter: FilterOpt = None,
+    sdk: Annotated[list[str] | None, typer.Option(help="Filter by SDK (e.g. gradio, docker, static).")] = None,


CLI sdk parameter type allows unsupported multi-value input

Low Severity

The CLI declares sdk as list[str] | None, allowing users to pass multiple --sdk values (e.g. --sdk gradio --sdk docker). The API method also accepts list[str]. However, the semantic search endpoint documentation and CLI help text ("Filter by SDK (e.g. gradio, docker, static).") imply a single value. This was also flagged by a reviewer suggesting sdk: str | None. Passing multiple SDK values may produce unexpected server behavior or silently drop values.

Additional Locations (1)

src/huggingface_hub/hf_api.py#L2913-L2914

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

hanouticelina

Thanks!

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

mishig25 · 2026-04-14T09:38:13Z

+Examples
+  $ hf spaces search "generate image"
+  $ hf spaces search "chatbot" --sdk gradio --limit 5
+  $ hf spaces search "animate image" --description --json


since it is a semantic search, we can provide one example showing a longer sentence query, not just 2-3 keywords

do you have a good example?

remove background from photo

identify objects in pictures

thanks

added them in examples:

(huggingface_hub) ➜ huggingface_hub git:(add-space-semantic-search) ✗ hf spaces search "identify objects in pictures" --sdk gradio --limit 5 ID TITLE SDK LIKES STAGE CATEGORY SCORE ----------------------------------- --------------------------- ------ ----- ------- ---------------- ----- mrfakename/Z-Image-Turbo Z Image Turbo gradio 2874 RUNNING Image Generation 0.77 prithivMLmods/FireRed-Image-Edit... FireRed Image Edit 1.0 Fast gradio 810 RUNNING Image Editing 0.73 prithivMLmods/SAM3-Plus-Qwen3.5 SAM3 + Qwen3.5 gradio 13 RUNNING Object Detection 0.7 allenai/WildDet3D AI2 - WildDet3D gradio 14 RUNNING Object Detection 0.69 black-forest-labs/FLUX.2-klein-9B FLUX.2 [Klein] 9B gradio 742 RUNNING Image Generation 0.68 Hint: Use --description to show AI-generated descriptions. (huggingface_hub) ➜ huggingface_hub git:(add-space-semantic-search) ✗ hf spaces search "remove background from photo" --description --json --limit 1| jq [ { "id": "briaai/BRIA-RMBG-1.4", "title": "BRIA RMBG 1.4", "sdk": "gradio", "likes": 871, "stage": "RUNNING", "category": "Image Editing", "score": 0.87, "description": "Remove background from your photos instantly" } ]

mishig25 · 2026-04-16T10:33:06Z

could we release new version of cli so that I can have this change? 🙏

hanouticelina · 2026-04-16T10:34:55Z

@mishig25 yes we'll do a release today!

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

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

[CLI] Add hf spaces search command with semantic search

06d361f

Add `search_spaces()` method to `HfApi` and `hf spaces search <query>` CLI command that calls the Hub's semantic search API (`/api/spaces/semantic-search`). Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Wauplin requested review from hanouticelina and mishig25 April 13, 2026 13:56

Wauplin marked this pull request as ready for review April 13, 2026 14:07

hanouticelina reviewed Apr 13, 2026

View reviewed changes

Comment thread src/huggingface_hub/hf_api.py

Comment thread src/huggingface_hub/_space_api.py Outdated

hanouticelina reviewed Apr 13, 2026

View reviewed changes

Wauplin added 4 commits April 13, 2026 21:56

Merge branch 'main' into add-space-semantic-search

ac2147d

add search_spaces first class citizen

ed7aee7

update SpaceSearchResult creation

d894472

allow multiple sdks

b7c430f

Wauplin requested a review from hanouticelina April 13, 2026 20:07

cursor Bot reviewed Apr 13, 2026

View reviewed changes

hanouticelina approved these changes Apr 14, 2026

View reviewed changes

Comment thread docs/source/en/guides/manage-spaces.md Outdated

Comment thread docs/source/en/guides/manage-spaces.md Outdated

Wauplin and others added 2 commits April 14, 2026 10:43

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

e95af58

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

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

de255aa

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

mishig25 reviewed Apr 14, 2026

View reviewed changes

Comment thread docs/source/en/package_reference/cli.md

mishig25 reviewed Apr 14, 2026

View reviewed changes

Wauplin added 2 commits April 14, 2026 12:18

better examples

dacdb60

beter examples

7f23ec9

Wauplin merged commit b3a8eb5 into main Apr 15, 2026
17 of 21 checks passed

Wauplin deleted the add-space-semantic-search branch April 15, 2026 11:45

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

Conversation

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

Uh oh!

hf spaces search "generate image"

hf spaces search "chatbot" --sdk gradio --limit 2

hf spaces search "remove background from photo" --description --json --limit 1| jq

Uh oh!

bot-ci-comment Bot commented Apr 13, 2026

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hanouticelina Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Apr 13, 2026

Choose a reason for hiding this comment

CLI sdk parameter type allows unsupported multi-value input

Uh oh!

hanouticelina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mishig25 Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Wauplin Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

mishig25 Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mishig25 commented Apr 16, 2026

Uh oh!

hanouticelina commented Apr 16, 2026

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 13, 2026 •

edited

Loading

`hf spaces search "generate image"`

`hf spaces search "chatbot" --sdk gradio --limit 2`

`hf spaces search "remove background from photo" --description --json --limit 1| jq`

Wauplin Apr 14, 2026 •

edited

Loading