Summary

WIP and happy to discuss if it makes sense!

Using agents with Spaces, I found it helpful to give access to logs, and currently, this isn't exposed in the CLI. An alternative design would be to just return the URL for logs from methods that create /modify Spaces, but this might be better for actual scripting, etc.

• Adds HfApi.fetch_space_logs(repo_id, *, build=False, follow=False) — programmatic access to Space build/run logs via the SSE endpoint /api/spaces/{repo_id}/logs/{run|build}
• Adds hf spaces logs <repo_id> [--build] [-f/--follow] [-n/--tail N] CLI command
• 7 mock-based CLI tests, docs in manage-spaces guide + package reference

Note: This is a first pass — the API shape and implementation approach are open to discussion. Happy to iterate on naming, flag style, or the streaming/retry strategy based on feedback.

Motivation

Agents and scripts that manage Spaces (restart, set volumes, push code) currently have no way to read why a Space failed without knowing the raw endpoint URL and crafting a curl request. get_space_runtime() surfaces the stage (BUILD_ERROR, RUNTIME_ERROR) but not the actual error — that lives behind /api/spaces/{repo_id}/logs/{build|run}.

By wrapping this as a first-class method, agents can autonomously check logs when something goes wrong — no human nudge needed to provide a URL or paste output. The pattern already exists for Jobs (fetch_job_logs + hf jobs logs); this closes the equivalent gap for Spaces.

API shape

# Run logs (default) — like `docker logs`
for line in api.fetch_space_logs("username/my-space"):
    print(line, end="")

# Build logs — for BUILD_ERROR debugging
for line in api.fetch_space_logs("username/my-space", build=True):
    print(line, end="")

# Stream in real time
for line in api.fetch_space_logs("username/my-space", follow=True):
    print(line, end="")

hf spaces logs username/my-space              # run logs
hf spaces logs username/my-space --build      # build logs
hf spaces logs username/my-space -f           # stream
hf spaces logs username/my-space -n 50        # last 50 lines

Design decisions (all open for discussion)

build=True boolean flag vs log_type="build" enum. We tested this by prompting an independent agent with no knowledge of the implementation to write the CLI/Python calls they'd intuitively expect. They converged on --build as a boolean toggle (like kubectl logs --previous) rather than --type build as an enum. Rationale: shorter, no string literal to remember, honours the asymmetry ("logs" = run logs by default, build is the special case).

No SpaceStage polling in the helper. The helper trusts that and does not poll get_space_runtime() as a backstop. Upstream misbehavior (observed on one RUNTIME_ERROR space where the server held the socket open with zero bytes) is bounded by read timeout + retry cap. This avoids coupling to the SpaceStage enum, which is currently incomplete (server returns SLEEPING but the Python enum doesn't have it).

Single method, not separate fetch_space_logs + fetch_space_build_logs. Since both log endpoints share Iterable[str] and only differ by a URL segment, a single method with a boolean toggle felt like the right granularity but open to splitting if preferred.

Test plan

• 7 mock-based CLI tests (default, --follow, --build, --tail, --follow+--tail error, 404, 403)
• make style + make quality clean (2 pre-existing ty errors in cli/_output.py, not introduced here)
• Full test_cli.py — 228/228 passing
• Live-tested against real Spaces in RUNTIME_ERROR, RUNNING, and SLEEPING stages