ani-cli-web/README.md

ani-cli web

A local web UI for a system-wide ani-cli install.

Current version: 0.29.1

Project Layout

ani-cli-web/
  app.py          Public entrypoint, runtime wiring, watchlist domain logic, and CLI startup.
  app_support.py  Shared runtime/state/config helpers plus queue and library file utilities.
  queue_jobs.py   Download queue and background watchlist-refresh workers.
  watchlist_identity.py Safer watchlist identity resolution for queued download jobs.
  title_matching.py Shared anime-title normalization and matching helpers.
  http_handler.py HTTP route handling, request parsing, and remote-access guard.
  web_templates.py Shared Search, Config, and Watchlist page markup aggregation.
  search_page.py  Search page template.
  config_page.py  Config page template.
  watchlist_page.py Watchlist page template.
  template_helpers.py Shared page-shell navigation and sidebar brand 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:

./ani-cli-web

For thumbnail debugging, run:

./ani-cli-web --debug

The launcher also accepts ---debug. You can also enable debug logging with ANI_CLI_WEB_DEBUG=1.

Then open:

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.
• Watchlist category tabs for Watching, Planned, Finished, and Dropped, with per-anime category editing.
• AnimeSchedule-backed watchlist completion tracking that compares live sub/dub availability with the expected total episode count when known.
• Automatic watchlist sync after successful downloads, including downloaded-vs-manual finished markers.
• Per-show background watchlist refresh queueing so adding a show or syncing a finished download does not block the request on upstream episode, schedule, and thumbnail lookups.
• Queued per-show watchlist refresh work now survives app restarts and resumes from rows still marked queued.
• Per-show watchlist refresh queueing now also deduplicates in-flight refreshes, so the same show is not fetched twice back-to-back while one refresh is already running.
• The watchlist page now silently refreshes itself while queued per-show refresh work is still being processed, so queued entries settle into their updated state without a manual reload.
• The watchlist page now also avoids re-triggering the same unresolved thumbnail warm-up request on every silent poll cycle while a show's thumbnail state is unchanged.
• Background Refresh All execution with status polling, parallel per-show refresh work, and no inline thumbnail downloads during the bulk job.
• Search and Watchlist polling now use a shared serial browser polling helper so slow responses do not cause overlapping poll requests to pile up in the background.
• That shared browser polling helper now also tears itself down on page unload and uses chained setTimeout scheduling instead of a bare repeating interval.
• Controlled shutdown and runtime reset now cancel active download workers when waiting for teardown, reducing the chance of orphaned background downloads outliving the web process.
• Runtime reset now also refuses to clear the active global runtime when background workers fail to stop cleanly, preventing stale workers from outliving the runtime object that created them.
• Watchlist refresh networking now uses a shorter dedicated timeout, which helps per-show and bulk watchlist shutdown paths settle more predictably when upstream metadata services are slow.
• 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 and backend services split into dedicated modules while keeping app.py and web_templates.py as stable public aggregation points.
• Broader regression coverage for higher-risk queue, watchlist, remote-access, and handler flows.
• Search and watchlist requests guard against stale out-of-order async responses during rapid repeated actions.
• Search-page queue polling also guards against stale out-of-order refresh responses now.
• Queue log writes are batched during active downloads to reduce SQLite churn on noisy jobs.
• Queue persistence now stores core job metadata and logs in structured SQLite columns instead of treating the whole job as one large JSON blob.
• Queue worker startup failures now degrade into a normal failed job state instead of crashing the background queue thread.
• Failed and canceled downloads now clean their project-local staging directories automatically so partial files do not accumulate under .ani-cli-web/staging/.
• Failed thumbnail refresh attempts now record a retry timestamp, so unresolved covers back off instead of immediately requerying upstream sources on every later warm-up.
• Download-to-watchlist fallback matching now keeps season and part identity intact while still tolerating equivalent season notation such as 2nd Season vs Season 2.
• 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:

ANI_CLI_WEB_ALLOW_REMOTE=1
ANI_CLI_WEB_REMOTE_TOKEN=choose-a-long-random-token

Non-local clients must then send either:

• Authorization: Bearer <token>
• X-AniCli-Web-Token: <token>

When the app is placed behind a loopback reverse proxy, forwarded external client IP headers such as X-Forwarded-For are also treated as non-local, so proxied internet or LAN traffic still needs the token.

This keeps the queue, config, and watchlist APIs safer when the app is intentionally exposed beyond localhost.

Download Queue

The queue is stored in SQLite and shown 10 jobs at a time.

Core queue fields and logs are now stored in structured SQLite columns, while JSON payload storage is kept only for extra fields that do not have dedicated columns yet.

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:

ANI_CLI_DOWNLOAD_DIR/anime_name/Season 01/anime_name - S01E01.mp4

Watchlist

The watchlist stores one row per show in SQLite, keeps separate sub and dub episode counts, and assigns each show to one of four categories:

• Watching
• Planned
• Finished
• Dropped

You can add entries in two ways:

1. From the Search page with Add to watchlist, choosing the category first.
2. Manually on /watchlist with a title, AllAnime show_id, and category.

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, preserves interrupted job status across restarts, and refreshes shows in parallel without doing inline thumbnail downloads for every entry.
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/<show_id> 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.
8. Episode pills show current / total progress when AnimeSchedule exposes the planned episode count.
9. Sub and Dub pills turn green and gain Sub ready or Dub ready tags when that release track appears fully finished and ready for download.
10. Each category has its own tab on the watchlist page.
11. Every card includes an inline category selector so you can move tracked anime between tabs at any time.
12. Finished shows display a small check badge: green means the anime was downloaded through the app, gray means it was marked finished manually.

Download Sync

Successful downloads now feed back into the watchlist automatically.

Current behavior:

• If the anime is already on the watchlist, a successful download marks it as downloaded and keeps its current category.
• If the anime is not yet on the watchlist, ani-cli-web creates a new watchlist entry in Finished after the download succeeds.
• Those add and download-sync paths now queue a background refresh for episode counts, AnimeSchedule metadata, and thumbnails instead of waiting for all upstream fetches before returning.
• If a queued job ever reaches the older search-based fallback path for show_id resolution, the app now only accepts that fallback when the queued title still matches the returned result confidently, preferring to fail safe over marking the wrong anime as downloaded.
• That fallback now also preserves season and part distinctions, so Season 2 downloads do not silently sync against a different season with the same base title.
• When that safer fallback still cannot resolve a show_id, the failure now keeps the specific reason so logs and error messages are easier to diagnose.
• Existing watchlist entries from older versions are migrated into the Watching category automatically.

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.
• The page only retries an unresolved cover warm-up once per thumbnail state change during the current browser session, so silent watchlist polling does not keep hammering the same missing poster.
• If a show disappears while a thumbnail warm-up batch is running, that entry is skipped cleanly instead of failing the whole batch request.
• 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.
• Stale stored AnimeSchedule routes and AniDB IDs now fall back to fresh title-based lookups instead of aborting the whole thumbnail refresh attempt.
• 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.
• AniDB fallback reuses the cached parsed title list directly to keep repeated lookups lighter.
• Failed automatic fetch attempts now start the retry window, so bad lookups back off instead of hammering AnimeSchedule and AniDB on every warm-up pass.

Watchlist Pagination

Watchlist listing responses now clamp out-of-range page requests to the last available page before querying rows, so the returned page number and items stay consistent even when the browser or API client asks for a page past the end.

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.

Completion Detection

Watchlist refresh still uses AllAnime, the same upstream source that ani-cli uses, to count which sub and dub episodes are actually available right now.

To decide whether a release track looks complete, ani-cli-web also checks AnimeSchedule for:

• the anime's expected total episode count
• the upstream airing status such as Finished or Ongoing

When AnimeSchedule reports a known total and Finished, the watchlist compares that total with the live AllAnime sub and dub counts:

• Sub becomes ready when available sub episodes reach the expected total.
• Dub becomes ready when available dub episodes reach the expected total.

If AnimeSchedule does not know the total yet, the watchlist keeps showing the plain available-count value without a completion highlight.

Runtime State

All runtime state is stored under:

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_REMOTE_TOKEN: required shared secret for non-loopback clients when remote access is enabled.
• 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.
• Importing app_support.py no longer migrates or creates runtime state on its own; migrations now happen during runtime bootstrap.
• Cheap routes such as the page shells, /api/version, /api/dependencies, and /api/config do not need to boot the full runtime before responding.
• The CLI startup path itself also stays lazy now; runtime bootstrap happens when the first runtime-backed request arrives.
• 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.