# ani-cli web A local web UI for a system-wide `ani-cli` install. Current version: `0.12.0` ## Project Layout ```text ani-cli-web/ app.py Web server, runtime wiring, request handlers, and CLI entrypoint. web_templates.py Shared Search, Config, and Watchlist page markup plus page-shell helpers. ani-cli-web Launcher script. test_app.py Regression tests with isolated temp-state setup. VERSION Project version. CHANGELOG.md Change history. README.md Project documentation. ``` ## Run Start the web app with: ```sh ./ani-cli-web ``` For thumbnail debugging, run: ```sh ./ani-cli-web --debug ``` The launcher also accepts `---debug`. You can also enable debug logging with `ANI_CLI_WEB_DEBUG=1`. Then open: ```text http://127.0.0.1:8421/ ``` By default the server binds to `127.0.0.1:8421`. ## Overview `ani-cli-web` keeps search and download management on `/`, saved defaults on `/config`, and the watchlist on `/watchlist`, all with the same sidebar navigation layout and a Tsuki-inspired visual style. The app currently includes: - Search against AllAnime with `sub` or `dub` mode selection. - Episode loading for the selected result. - Queueing downloads with editable library name, season, episode range, quality, and target folder. - A dedicated Config page for saved default folder, mode, and quality settings. - A paged SQLite-backed download queue with retry, cancel, remove, retry-failed, and clear-finished actions. - A paged SQLite-backed watchlist with summary cards, per-show refresh, bulk refresh, source links, and thumbnail tools. - Background `Refresh All` execution with status polling instead of a long blocking HTTP request. - Persistent watchlist refresh history that survives restarts and marks interrupted bulk refresh jobs clearly. - Local thumbnail caching plus manual thumbnail upload when automatic cover lookup fails. - A refreshed glassy dark UI inspired by the Tsuki frontend design language. - Shared page templates moved out of `app.py` plus broader regression tests for higher-risk queue, watchlist, and handler flows. - Project-local runtime state under `.ani-cli-web/`. ## Search Page The main page at `/` is where you search and queue downloads. Workflow: 1. Search by anime title or keyword. 2. Pick a result to load available episodes. 3. Adjust library name, season, episode range, quality, and download folder. 4. Add the selected show either to the watchlist or directly to the queue. The page also includes: - A live queue view that refreshes automatically. ## Config Page The Config page at `/config` is where saved defaults now live. Use it to: 1. Set the default download folder. 2. Choose the default `sub` or `dub` search mode. 3. Choose the default search quality used to prefill the Search page. Those saved defaults are written into the project-local `config.json` and loaded automatically when the Search page opens. The Config page also shows the current app version plus dependency status in a compact centered layout. ## Access Guard By default, `ani-cli-web` only serves loopback clients such as `127.0.0.1` and `::1`. If you intentionally want LAN or remote access, set: ```sh ANI_CLI_WEB_ALLOW_REMOTE=1 ``` This keeps the queue, config, and watchlist mutation APIs safer by default when the app is rebound away from localhost. ## Download Queue The queue is stored in SQLite and shown 10 jobs at a time. Queue actions currently available: - `Retry` for finished or failed jobs. - `Cancel` for pending or running jobs. - `Remove` for completed or failed jobs. - `Retry failed` for all failed jobs. - `Remove finished` for completed jobs. Downloads are staged inside the project-local app state first. After `ani-cli` finishes, files are moved into a Plex/Jellyfin-friendly layout: ```text ANI_CLI_DOWNLOAD_DIR/anime_name/Season 01/anime_name - S01E01.mp4 ``` ## Watchlist The watchlist stores one row per show in SQLite and keeps separate `sub` and `dub` episode counts. You can add entries in two ways: 1. From the Search page with `Add to watchlist`. 2. Manually on `/watchlist` with a title and AllAnime `show_id`. Watchlist features: 1. `Refresh` updates one tracked show. 2. `Refresh All` runs in the background, rejects duplicate queueing while a refresh is already pending or running, and preserves interrupted job status across restarts. 3. `Open` jumps back to the Search page with the title pre-filled. 4. Clicking the anime title opens the AllManga source page at `bangumi/` in a new tab. 5. `Remove` deletes the watchlist entry and clears its cached poster file. 6. Poster cards use a compact multi-column grid with pagination at 30 cards per page. 7. Summary cards show tracked shows plus total `sub` and `dub` episode counts. ### Thumbnail Behavior Watchlist thumbnails use the local `/api/watchlist/thumb/...` route, not direct remote image URLs. Current thumbnail behavior: - Cached thumbnails render from the local project cache when available. - The page adds a fresh nonce to thumbnail URLs to avoid stale browser-cached misses. - Missing visible covers are warmed up in small batches instead of one request per card all at once. - Thumbnail image tags only hit the local route for already-cached files, so opening the watchlist no longer triggers a per-card remote lookup burst. - AnimeSchedule is tried first for cover lookup. - If a season-labeled title fails as-is, lookup retries with simplified base-title queries. - AniDB is used as a fallback when AnimeSchedule does not resolve a cover. - Failed fetch attempts no longer refresh the retry window, so a bad lookup does not get stuck in an immediate repeat-404 state. Per-card thumbnail tools: 1. `Reload` forces a fresh redownload attempt for that show's poster. 2. `Upload` appears when no thumbnail is currently available and lets you assign a local image manually. 3. Hovering the poster tile or card shows the current thumbnail source hint. Manual uploads are saved into the same local thumbnail cache used by automatic cover downloads. ## Runtime State All runtime state is stored under: ```text ani-cli-web/.ani-cli-web/ ``` That folder currently holds: - `config.json` - `state.sqlite3` - legacy `queue.json` migration input when present - legacy `watchlist.json` migration input when present - `thumbnails/` - AniDB title cache data - staging files for active downloads Legacy files from `~/.config/ani-cli-web/` and `~/.local/state/ani-cli-web/` are migrated into the project-local folder automatically on startup. The earlier project-local `queue.sqlite3` filename is also migrated automatically into `state.sqlite3`. ## Configuration Environment variables: - `ANI_CLI_BIN`: path or command name for `ani-cli`; defaults to `ani-cli` from `PATH`. - `ANI_CLI_DOWNLOAD_DIR`: initial default download folder. - `ANI_CLI_MODE`: initial mode, `sub` or `dub`. - `ANI_CLI_QUALITY`: initial quality such as `best`, `1080`, or `720`. - `ANI_CLI_WEB_HOST`: server host, default `127.0.0.1`. - `ANI_CLI_WEB_PORT`: server port, default `8421`. - `ANI_CLI_WEB_ALLOW_REMOTE`: allow non-loopback clients when set to `1`, `true`, `yes`, or `on`. - `ANI_CLI_WEB_DEBUG`: enable debug logging when set to `1`, `true`, `yes`, or `on`. - `ANI_CLI_WEB_STATE_ROOT`: override the project-local state directory path; useful for isolated test runs or custom storage locations. Saved defaults from the UI are written into the project-local `config.json`. ## Notes - Importing `app.py` no longer boots the runtime worker threads automatically; runtime setup is deferred until startup or first use. - Watchlist and queue data are stored in the same project-local SQLite database file, `state.sqlite3`. - Runtime folders such as `.ani-cli-web/`, `downloads/`, and Python bytecode cache directories at any depth are ignored by git. - Focused regression tests live in `test_app.py`, run against an isolated temporary state root, and can be started with `python3 -m unittest test_app.py`.