HTTP API

The daemon serves an axum router over both a Unix socket ($XDG_RUNTIME_DIR/alfred.sock, default) and an optional TCP listener. The CLI client speaks minimal hand-rolled HTTP to the same router.

Routes

Method	Path	Purpose
GET	/{module}	latest cached ModuleOutput JSON (one-shot)
GET	/stream/{module}	NDJSON stream, pushed on every update
POST	/control/{module}/{action}	trigger an action, then force an immediate refresh
GET	/modules	registered modules + their capabilities
GET	/events	journal event feed
POST	/automation/reload	reload the automation Lua scripts
POST	/music/search	forwarded to the ytm worker subprocess
GET	/music/library	forwarded to the ytm worker subprocess

Behaviour notes

• Control handlers run the side effect (often wpctl / playerctl / hyprctl, or native Hyprland dispatch), then publish + force_refresh so the next GET /{module} is already fresh. They return Result<String, String> mapped to HTTP status codes.
• YTMD volume uses an optimistic-update path (ytmd_volume_hint + a debounced background flush worker) so scroll handlers stay snappy.
• /music/* routes forward over the worker IPC protocol to the alfred-ytm subprocess (see Architecture → Worker subprocesses).

CLI ↔ route mapping

alfred get <module>            # GET /{module}
alfred stream <module>         # GET /stream/{module}
alfred control <module> <act>  # POST /control/{module}/{action}
alfred modules                 # GET /modules
alfred events                  # GET /events