fix(cli): point at an API key where the device flow is not served

[mikhail-koviazin]

Why

hud login cannot succeed against api.hud.ai:

$ hud login -q
✖ HUD API returned 404 when starting login.
{"error":"not_found","detail":"Not Found"}

The command posts to {settings.hud_api_url}/auth/device/code, and that route is not there under any prefix:

Request	Response
POST /auth/device/code	404 not_found
POST /v1/auth/device/code	404
POST /v2/auth/device/code	404
POST /v3/auth/device/code	404

The platform itself answers, so this is neither the base URL nor the network:

Request	Response
GET /v2/jobs	401 unauthorized
GET /v2/models	401
GET /openapi.json	200

The published contract has no such route either: https://api.hud.ai/openapi.json (HUD Platform 2.0.0) lists 103 paths, none of them containing auth, device, login or token.

Users are pointed at the command anyway. docs/v6/reference/cli.mdx lists hud login | Authenticate with HUD., and require_api_key makes it the first suggestion when a key is missing, ahead of the route that does work:

$ hud jobs
✖ No HUD API key found
A HUD API key is required to list jobs.
Run: hud login
Or get your key at: https://hud.ai/settings
Set it via: hud set HUD_API_KEY=your-key-here

What

A 404 from the device-code endpoint gets its own branch, so the one outcome every user currently reaches says what to do about it:

$ hud login -q
✖ No browser login at https://api.hud.ai/auth/device/code (404).
This HUD deployment does not serve the device flow.
Get your key at: https://hud.ai/settings
Set it via: hud set HUD_API_KEY=your-key-here

The wording is taken from require_api_key so the two messages agree. The branch is reached only on 404, so if the device flow ships later it stops firing on its own, and nothing else about the flow changes.

Deliberately left alone: whether hud login should exist while it cannot work, and the order of the hints in require_api_key. Those are product calls, not bugs.

Tests

hud/cli/tests/test_login.py is the first coverage login.py has. It drives the command through CliRunner with only the transport mocked, so the request path that runs is the real one.

• A 404 from the device-code endpoint tells the user where to get a key, and exits 1.
• Any other failure is still reported as it comes back, body and all, so the new branch cannot swallow an outage.

The first fails on main and the second passes there, which is why both are here.

Validation

• uv run pytest -q
• uv run ruff format . --check and uv run ruff check .
• uv run --extra dev --extra train --extra modal --extra daytona ty check --error-on-warning
• The before and after above are real runs against api.hud.ai, not written by hand.

---

Note

Low Risk
CLI-only error messaging and tests; no auth, API contract, or credential handling changes beyond clearer 404 UX.

Overview
When hud login gets a 404 from POST /auth/device/code, it no longer dumps the response body like a generic API failure. It explains that this deployment does not support browser/device login and steers users to settings.hud_web_url/settings and hud set HUD_API_KEY=..., aligned with the missing-key hints elsewhere in the CLI.

Non-404 errors on that request are unchanged: status code plus response snippet, exit 1.

Adds hud/cli/tests/test_login.py, exercising the real login command via CliRunner with only httpx.Client transport mocked—404 must mention API-key setup; 503 must still surface the upstream body.

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