[CLI] Add hf spaces search command with semantic search (#4094)

* [CLI] Add `hf spaces search` command with semantic search

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) <noreply@anthropic.com>

* add search_spaces first class citizen

* update SpaceSearchResult creation

* allow multiple sdks

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

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

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

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

* better examples

* beter examples

---------

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

@@ -8,6 +8,30 @@ In this guide, we will see how to manage your Space runtime
 ([secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets),
 [hardware](https://huggingface.co/docs/hub/spaces-gpus), and volumes) using `huggingface_hub`.
 
+## Search for Spaces
+
+You can search for Spaces on the Hub using semantic search with [`search_spaces`]. This uses embedding-based search for multi-word queries and full-text search for single-word queries.
+
+```py
+>>> from huggingface_hub import search_spaces
+>>> results = list(search_spaces("generate image"))
+>>> results[0]
+SpaceSearchResult(id='mrfakename/Z-Image-Turbo', title='Z Image Turbo', sdk='gradio', likes=2867, ...)
+```
+
+You can filter results by SDK or tags:
+
+```py
+>>> results = search_spaces("chatbot", sdk="gradio", filter="mcp-server")
+```
+
+Or via CLI:
+
+```bash
+>>> hf spaces search "generate image"
+>>> hf spaces search "chatbot" --sdk gradio --limit 5
+```
+
 ## A simple example: configure secrets and hardware.
 
 Here is an end-to-end example to create and set up a Space on the Hub.

docs/source/en/guides/repository.md

@@ -121,6 +121,19 @@ RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)
 RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)
 ```
 
+## Search for Spaces
+
+The Hub provides a semantic search API for discovering Spaces. You can search using natural language queries with [`search_spaces`]:
+
+```py
+>>> from huggingface_hub import search_spaces
+>>> results = list(search_spaces("generate image"))
+>>> results[0].id
+'mrfakename/Z-Image-Turbo'
+```
+
+For more details and filtering options, see the [Manage your Spaces](./manage-spaces#search-for-spaces) guide.
+
 ## Upload and download files
 
 Now that you have created your repository, you are interested in pushing changes to it and downloading files from it.

docs/source/en/package_reference/cli.md

@@ -3403,6 +3403,7 @@ $ hf spaces [OPTIONS] COMMAND [ARGS]...
 * `hot-reload`: Hot-reload any Python file of a Space...
 * `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...
 
 ### `hf spaces dev-mode`
 
@@ -3546,6 +3547,41 @@ Learn more
   Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
 
 
+### `hf spaces search`
+
+Search spaces on the Hub using semantic search.
+
+**Usage**:
+
+```console
+$ hf spaces search [OPTIONS] QUERY
+```
+
+**Arguments**:
+
+* `QUERY`: Search query.  [required]
+
+**Options**:
+
+* `--filter TEXT`: Filter by tags (e.g. 'text-classification'). Can be used multiple times.
+* `--sdk TEXT`: Filter by SDK (e.g. gradio, docker, static).
+* `--include-non-running / --no-include-non-running`: Include non-running spaces in results.  [default: no-include-non-running]
+* `--description / --no-description`: Show AI-generated descriptions.  [default: no-description]
+* `--limit INTEGER`: Limit the number of results.  [default: 10]
+* `--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 search "generate image"
+  $ hf spaces search "identify objects in pictures" --sdk gradio --limit 5
+  $ hf spaces search "remove background from photo" --description --json
+
+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.

docs/source/en/package_reference/hf_api.md

@@ -133,6 +133,10 @@ models = hf_api.list_models()
 
 [[autodoc]] huggingface_hub.hf_api.SpaceInfo
 
+### SpaceSearchResult
+
+[[autodoc]] huggingface_hub._space_api.SpaceSearchResult
+
 ### TensorInfo
 
 [[autodoc]] huggingface_hub.utils.TensorInfo

src/huggingface_hub/__init__.py

@@ -189,6 +189,7 @@
         "RepoFolder",
         "RepoUrl",
         "SpaceInfo",
+        "SpaceSearchResult",
         "User",
         "UserLikes",
         "WebhookInfo",
@@ -322,6 +323,7 @@
         "run_job",
         "run_uv_job",
         "scale_to_zero_inference_endpoint",
+        "search_spaces",
         "set_space_sleep_time",
         "set_space_volumes",
         "space_info",
@@ -794,6 +796,7 @@
     "SpaceHardware",
     "SpaceInfo",
     "SpaceRuntime",
+    "SpaceSearchResult",
     "SpaceStage",
     "SpaceStorage",
     "SpaceVariable",
@@ -1059,6 +1062,7 @@
     "save_torch_state_dict",
     "scale_to_zero_inference_endpoint",
     "scan_cache_dir",
+    "search_spaces",
     "set_async_client_factory",
     "set_client_factory",
     "set_space_sleep_time",
@@ -1319,6 +1323,7 @@ def __dir__():
         RepoFolder,  # noqa: F401
         RepoUrl,  # noqa: F401
         SpaceInfo,  # noqa: F401
+        SpaceSearchResult,  # noqa: F401
         User,  # noqa: F401
         UserLikes,  # noqa: F401
         WebhookInfo,  # noqa: F401
@@ -1452,6 +1457,7 @@ def __dir__():
         run_job,  # noqa: F401
         run_uv_job,  # noqa: F401
         scale_to_zero_inference_endpoint,  # noqa: F401
+        search_spaces,  # noqa: F401
         set_space_sleep_time,  # noqa: F401
         set_space_volumes,  # noqa: F401
         space_info,  # noqa: F401

src/huggingface_hub/_space_api.py

@@ -249,3 +249,69 @@ def __init__(self, key: str, values: dict) -> None:
         self.description = values.get("description")
         updated_at = values.get("updatedAt")
         self.updated_at = parse_datetime(updated_at) if updated_at is not None else None
+
+
+@dataclass
+class SpaceSearchResult:
+    """A single result from the Spaces semantic search API.
+
+    Returned by [`HfApi.search_spaces`].
+
+    Attributes:
+        id (`str`):
+            ID of the Space (e.g. `"username/repo-name"`).
+        author (`str`):
+            Author of the Space.
+        title (`str`):
+            Display title of the Space.
+        emoji (`str` or `None`):
+            Emoji icon of the Space.
+        sdk (`str` or `None`):
+            SDK used by the Space (e.g. `"gradio"`, `"docker"`, `"static"`).
+        likes (`int`):
+            Number of likes.
+        private (`bool`):
+            Whether the Space is private.
+        tags (`list[str]` or `None`):
+            List of tags.
+        runtime ([`SpaceRuntime`] or `None`):
+            Runtime information (stage, hardware, etc.).
+        ai_short_description (`str` or `None`):
+            AI-generated short description.
+        ai_category (`str` or `None`):
+            AI-generated category (e.g. `"Image Generation"`).
+        semantic_relevancy_score (`float` or `None`):
+            Semantic relevancy score (0-1) relative to the search query.
+        trending_score (`int` or `None`):
+            Trending score.
+    """
+
+    id: str
+    author: str
+    title: str
+    emoji: str | None
+    sdk: str | None
+    likes: int
+    private: bool
+    tags: list[str] | None
+    runtime: SpaceRuntime | None
+    ai_short_description: str | None
+    ai_category: str | None
+    semantic_relevancy_score: float | None
+    trending_score: int | None
+
+    def __init__(self, data: dict) -> None:
+        runtime = data.get("runtime")
+        self.id = data["id"]
+        self.author = data.get("author", "")
+        self.title = data.get("title", "")
+        self.emoji = data.get("emoji")
+        self.sdk = data.get("sdk")
+        self.likes = data.get("likes", 0)
+        self.private = data.get("private", False)
+        self.tags = data.get("tags")
+        self.runtime = SpaceRuntime(runtime) if runtime else None
+        self.ai_short_description = data.get("ai_short_description")
+        self.ai_category = data.get("ai_category")
+        self.semantic_relevancy_score = data.get("semanticRelevancyScore")
+        self.trending_score = data.get("trendingScore")

src/huggingface_hub/cli/spaces.py

@@ -26,6 +26,7 @@
 
 import enum
 import functools
+import itertools
 import os
 import shlex
 import shutil
@@ -144,6 +145,52 @@ def spaces_info(
     out.dict(info)
 
 
+@spaces_cli.command(
+    "search",
+    examples=[
+        'hf spaces search "generate image"',
+        'hf spaces search "identify objects in pictures" --sdk gradio --limit 5',
+        'hf spaces search "remove background from photo" --description --json',
+    ],
+)
+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,
+    include_non_running: Annotated[bool, typer.Option(help="Include non-running spaces in results.")] = False,
+    description: Annotated[bool, typer.Option(help="Show AI-generated descriptions.")] = False,
+    limit: LimitOpt = 10,
+    format: FormatWithAutoOpt = OutputFormatWithAuto.auto,
+    token: TokenOpt = None,
+) -> None:
+    """Search spaces on the Hub using semantic search."""
+    api = get_hf_api(token=token)
+    results = api.search_spaces(
+        query=query,
+        filter=filter,
+        sdk=sdk,
+        include_non_running=include_non_running,
+        token=token,
+    )
+    items = []
+    for r in itertools.islice(results, limit):
+        item: dict = {
+            "id": r.id,
+            "title": r.title,
+            "sdk": r.sdk,
+            "likes": r.likes,
+            "stage": r.runtime.stage if r.runtime else None,
+            "category": r.ai_category,
+            "score": round(r.semantic_relevancy_score, 2) if r.semantic_relevancy_score is not None else None,
+        }
+        if description:
+            item["description"] = r.ai_short_description
+        items.append(item)
+    out.table(items)
+    if not description:
+        out.hint("Use --description to show AI-generated descriptions.")
+
+
 @spaces_cli.command(
     "dev-mode",
     examples=[

src/huggingface_hub/hf_api.py

@@ -72,7 +72,7 @@
 from ._eval_results import EvalResultEntry, parse_eval_result_entries
 from ._inference_endpoints import InferenceEndpoint, InferenceEndpointScalingMetric, InferenceEndpointType
 from ._jobs_api import JobHardware, JobInfo, JobSpec, ScheduledJobInfo, _create_job_spec
-from ._space_api import SpaceHardware, SpaceRuntime, SpaceStorage, SpaceVariable, Volume
+from ._space_api import SpaceHardware, SpaceRuntime, SpaceSearchResult, SpaceStorage, SpaceVariable, Volume
 from ._upload_large_folder import upload_large_folder_internal
 from .community import (
     Discussion,
@@ -2905,6 +2905,65 @@ def list_spaces(
                 item["siblings"] = None
             yield SpaceInfo(**item)
 
+    @validate_hf_hub_args
+    def search_spaces(
+        self,
+        query: str,
+        *,
+        filter: str | Iterable[str] | None = None,
+        sdk: str | list[str] | None = None,
+        include_non_running: bool = False,
+        token: bool | str | None = None,
+    ) -> Iterable[SpaceSearchResult]:
+        """Search Spaces on the Hub using semantic search.
+
+        This endpoint uses semantic search (embedding-based) for multi-word queries
+        and full-text search for single-word queries.
+
+        Args:
+            query (`str`):
+                The search query string.
+            filter (`str` or `Iterable[str]`, *optional*):
+                A string tag or list of tags to filter by.
+            sdk (`str` or `list[str]`, *optional*):
+                Filter by SDK (e.g. `"gradio"`, `"docker"`, `"static"`).
+            include_non_running (`bool`, *optional*):
+                Whether to include non-running Spaces in results. Defaults to `False`.
+            token (`bool` or `str`, *optional*):
+                A valid user access token (string). Defaults to the locally saved
+                token, which is the recommended method for authentication (see
+                https://huggingface.co/docs/huggingface_hub/quick-start#authentication).
+                To disable authentication, pass `False`.
+
+        Returns:
+            `Iterable[SpaceSearchResult]`: an iterable of [`SpaceSearchResult`] objects.
+
+        Example:
+            ```python
+            >>> from huggingface_hub import HfApi
+            >>> api = HfApi()
+            >>> results = list(api.search_spaces("generate image"))
+            >>> results[0].id
+            'mrfakename/Z-Image-Turbo'
+            >>> results[0].ai_category
+            'Image Generation'
+            ```
+        """
+        path = f"{self.endpoint}/api/spaces/semantic-search"
+        headers = self._build_hf_headers(token=token)
+        params: dict[str, Any] = {"q": query}
+        if filter is not None:
+            params["filter"] = filter
+        if sdk is not None:
+            params["sdk"] = sdk
+        if include_non_running:
+            params["includeNonRunning"] = True
+
+        r = get_session().get(path, headers=headers, params=params)
+        hf_raise_for_status(r)
+        for item in r.json():
+            yield SpaceSearchResult(item)
+
     @validate_hf_hub_args
     def unlike(
         self,
@@ -13581,6 +13640,7 @@ def get_local_safetensors_metadata(path: str | Path) -> SafetensorsRepoMetadata:
 get_dataset_leaderboard = api.get_dataset_leaderboard
 
 list_spaces = api.list_spaces
+search_spaces = api.search_spaces
 space_info = api.space_info
 
 kernel_info = api.kernel_info