[Spaces] Add fetch_space_logs + hf spaces logs command (#4091)

* [Spaces] Add fetch_space_logs + hf spaces logs command

Agents and scripts currently have no way to read Space build/run logs
programmatically — the endpoint is only reachable via raw curl. This
adds a public API to close that gap.

- HfApi.fetch_space_logs(repo_id, *, build=False, follow=False) yields
  log lines as Iterable[str]. build=True switches to container build
  logs; default is the running app's stdout/stderr.
- `hf spaces logs <repo_id> [--build] [-f] [-n N]` mirrors the Python
  API at the CLI level, with 404/403 mapped to clean CLIError messages.

The helper trusts the "stream close = done" server contract (confirmed
against moon-landing's SpaceLogs.svelte onClose handler) and does not
poll SpaceStage; read timeout + bounded retries handle the
misbehaving-upstream case. Structure mirrors _fetch_running_job_sse but
without the status-check backstop. Tests use the mock-based pattern
from hf jobs logs (no new VCR cassettes).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update generated CLI reference for hf spaces logs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix: catch HfHubHTTPError instead of httpx.HTTPStatusError

hf_raise_for_status() raises HfHubHTTPError (inherits HTTPError), not
httpx.HTTPStatusError. The previous handler was dead code, causing
404/403 errors to fall through to the retry loop instead of raising
immediately. Spotted by cursor bugbot on PR review.

Note: the same bug exists in _fetch_running_job_sse — not fixed here
to keep the diff focused, but worth a follow-up.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

Co-authored-by: Lucain <lucainp@gmail.com>

* Refactor: share SSE streaming loop between Spaces and Jobs

Extracts `HfApi._stream_sse_events` to unify the retry/backoff/dedup
loop previously duplicated across `_fetch_space_logs_sse` and
`_fetch_running_job_sse`. Addresses Wauplin and Cursor Bugbot review
comments on PR #4091.

Also fixes a dead `except httpx.HTTPStatusError` handler that affected
both Spaces and Jobs: `hf_raise_for_status` raises `HfHubHTTPError`
(subclass of `httpx.HTTPError`, not `HTTPStatusError`), so 404/403 in
follow mode used to fall through to the broad retry arm and stall for
~25s. The new helper catches `HfHubHTTPError` before the broad arm, so
permanent errors fail fast. Live-verified: `hf spaces logs missing/x -f`
now errors in <1s instead of ~25s.

CLI cleanups on `hf spaces logs` per Wauplin:
- Switch from `print()` to `out.text(line.strip())` (new mode-aware
  printer from #3979).
- Drop the redundant local `HfHubHTTPError` block — it's already
  handled by the global CLI error mapper.

Also tightens `_fetch_running_job_sse` typing by splitting the legacy
`double_check_job_has_finished_on_status_code_or_error` mixed tuple
into `tolerated_status_codes: tuple[int, ...]` and
`tolerated_exception_types: tuple[type[Exception], ...]`, eliminating a
runtime type-discrimination step.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Drop dead `httpx.ReadTimeout` entry from fetch_job_metrics

The entry in `tolerated_exception_types` was never consulted: the SSE
helper's `is_no_new_line_timeout` check short-circuits the tolerated
tuple lookup for any ReadTimeout, so the tuple entry was dead code
(pre-existing on `main` before #4091, preserved faithfully through the
refactor). ReadTimeout tolerance continues to work via the
`is_no_new_line_timeout` path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update src/huggingface_hub/cli/spaces.py

Co-authored-by: Lucain <lucainp@gmail.com>

* Update tests/test_cli.py

Co-authored-by: Lucain <lucainp@gmail.com>

* Update tests/test_cli.py

Co-authored-by: Lucain <lucainp@gmail.com>

* Address review feedback on fetch_space_logs

- Promote "Debug a failing Space" heading to ### (matches PR #4108 style)
- Add hint when run logs are empty, suggesting --build as alternative
- Add tests covering the empty-logs hint for both run and build modes
- Regenerate CLI reference docs to include hf spaces logs command

* Update tests/test_cli.py

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Lucain <lucainp@gmail.com>

Author: 3 people

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

@@ -195,6 +195,33 @@ it will go to sleep. Any visitor landing on your Space will start it back up. Yo
 Note: if you are using a 'cpu-basic' hardware, you cannot configure a custom sleep time. Your Space will automatically
 be paused after 48h of inactivity.
 
+### Debug a failing Space by reading its logs
+
+When a Space fails to build or crashes at runtime, the logs you normally view in the browser are also available programmatically via [`fetch_space_logs`]. This is particularly useful from scripts or agentic workflows where opening a browser is not an option.
+
+```py
+# Drain the currently available run logs and return immediately (like `docker logs`)
+>>> for line in api.fetch_space_logs(repo_id=repo_id):
+...     print(line, end="")
+
+# Read the container build logs instead (useful when the Space is stuck in BUILD_ERROR)
+>>> for line in api.fetch_space_logs(repo_id=repo_id, build=True):
+...     print(line, end="")
+
+# Stream run logs in real time until the server closes the stream (Ctrl-C to stop)
+>>> for line in api.fetch_space_logs(repo_id=repo_id, follow=True):
+...     print(line, end="")
+```
+
+The same functionality is available from the CLI:
+
+```bash
+hf spaces logs username/my-space             # drain run logs
+hf spaces logs username/my-space --build     # read build logs
+hf spaces logs username/my-space -f          # stream in real time
+hf spaces logs username/my-space -n 50       # last 50 lines only
+```
+
 **Bonus: set a sleep time while requesting hardware**
 
 Upgraded hardware will be automatically assigned to your Space once it's built.

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]
+* `logs`: Fetch the run or build logs of a Space.
 * `search`: Search spaces on the Hub using semantic...
 * `volumes`: Manage volumes for a Space on the Hub.
 
@@ -3548,6 +3549,44 @@ Learn more
   Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
 
 
+### `hf spaces logs`
+
+Fetch the run or build logs of a Space.
+
+By default, prints currently available run logs and exits (non-blocking, like
+`docker logs`). Use --follow/-f to stream until the server closes the stream.
+Use --build to see the container build logs instead (useful when a Space is
+stuck in BUILD_ERROR).
+
+**Usage**:
+
+```console
+$ hf spaces logs [OPTIONS] SPACE_ID
+```
+
+**Arguments**:
+
+* `SPACE_ID`: The space ID (e.g. `username/repo-name`).  [required]
+
+**Options**:
+
+* `--build`: Fetch the container build logs instead of the run logs. Useful when a Space is stuck in BUILD_ERROR.
+* `-f, --follow`: Follow log output (stream until the server closes the stream). Without this flag, only currently available logs are printed.
+* `-n, --tail INTEGER`: Number of lines to show from the end of the logs.
+* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
+* `--help`: Show this message and exit.
+
+Examples
+  $ hf spaces logs username/my-space
+  $ hf spaces logs username/my-space --build
+  $ hf spaces logs -f username/my-space
+  $ hf spaces logs -n 50 username/my-space
+
+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 spaces search`
 
 Search spaces on the Hub using semantic search.

docs/source/en/package_reference/space_runtime.md

@@ -8,6 +8,7 @@ Check the [`HfApi`] documentation page for the reference of methods to manage yo
 
 - Duplicate a Space: [`duplicate_space`]
 - Fetch current runtime: [`get_space_runtime`]
+- Fetch build or run logs: [`fetch_space_logs`]
 - Manage secrets: [`add_space_secret`] and [`delete_space_secret`]
 - Manage hardware: [`request_space_hardware`]
 - Manage state: [`pause_space`], [`restart_space`], [`set_space_sleep_time`]

src/huggingface_hub/__init__.py

@@ -245,6 +245,7 @@
         "enable_webhook",
         "fetch_job_logs",
         "fetch_job_metrics",
+        "fetch_space_logs",
         "file_exists",
         "get_bucket_file_metadata",
         "get_bucket_paths_info",
@@ -954,6 +955,7 @@
     "export_folder_as_dduf",
     "fetch_job_logs",
     "fetch_job_metrics",
+    "fetch_space_logs",
     "file_exists",
     "from_pretrained_fastai",
     "get_async_session",
@@ -1379,6 +1381,7 @@ def __dir__():
         enable_webhook,  # noqa: F401
         fetch_job_logs,  # noqa: F401
         fetch_job_metrics,  # noqa: F401
+        fetch_space_logs,  # noqa: F401
         file_exists,  # noqa: F401
         get_bucket_file_metadata,  # noqa: F401
         get_bucket_paths_info,  # noqa: F401

src/huggingface_hub/cli/spaces.py

@@ -34,6 +34,7 @@
 import sys
 import tempfile
 import time
+from collections import deque
 from typing import Annotated, Literal, get_args
 
 import typer
@@ -264,6 +265,68 @@ def dev_mode(
     print("PS: Dev mode stops after 48h of inactivity, don't forget to save your changes regularly.")
 
 
+@spaces_cli.command(
+    "logs",
+    examples=[
+        "hf spaces logs username/my-space",
+        "hf spaces logs username/my-space --build",
+        "hf spaces logs -f username/my-space",
+        "hf spaces logs -n 50 username/my-space",
+    ],
+)
+def spaces_logs(
+    space_id: Annotated[str, typer.Argument(help="The space ID (e.g. `username/repo-name`).")],
+    build: Annotated[
+        bool,
+        typer.Option(
+            "--build",
+            help="Fetch the container build logs instead of the run logs. Useful when a Space is stuck in BUILD_ERROR.",
+        ),
+    ] = False,
+    follow: Annotated[
+        bool,
+        typer.Option(
+            "-f",
+            "--follow",
+            help="Follow log output (stream until the server closes the stream). Without this flag, only currently available logs are printed.",
+        ),
+    ] = False,
+    tail: Annotated[
+        int | None,
+        typer.Option(
+            "-n",
+            "--tail",
+            help="Number of lines to show from the end of the logs.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Fetch the run or build logs of a Space.
+
+    By default, prints currently available run logs and exits (non-blocking, like
+    `docker logs`). Use --follow/-f to stream until the server closes the stream.
+    Use --build to see the container build logs instead (useful when a Space is
+    stuck in BUILD_ERROR).
+    """
+    if follow and tail is not None:
+        raise CLIError(
+            "Cannot use --follow and --tail together. Use --follow to stream logs or --tail to show recent logs."
+        )
+
+    api = get_hf_api(token=token)
+    logs = api.fetch_space_logs(space_id, build=build, follow=follow)
+    if tail is not None:
+        logs = deque(logs, maxlen=tail)
+    found_logs = False
+    for line in logs:
+        clean_line = line.strip()
+        out.text(clean_line)
+        if clean_line:
+            found_logs = True
+    if not found_logs and not build:
+        out.hint(f"No run logs found for space {space_id}. Try passing --build to fetch build logs instead.")
+
+
 @spaces_cli.command(
     "hot-reload",
     examples=[