anipy-cli: anime watching from the terminal, with a separate API package

Two PyPI packages split out of one repository

The structural change that matters in this project happened in the version 3 rewrite, and the README states it plainly: the project is split into api and frontend, which makes it easy to integrate anipy-cli into your own project.

That split is visible in the distribution. The client is published as anipy-cli on PyPI and the library as anipy-api, each with its own version badge in the README and its own getting started page on the documentation site. The repository reflects the same separation with an api/ directory and a cli/ directory at the top level, alongside docs/, scripts/, mkdocs.yml, poetry.lock, flake.nix, shell.nix and an .envrc.

The two packages are also wired together at the packaging level. The pyproject file at the repository root declares the dependency on the client as a local path in develop mode:

[tool.poetry.dependencies]
python = "^3.10"
anipy-cli = {path = "cli/", develop = true}

Python 3.10 is the floor, and the root manifest sets package-mode to false, which is consistent with a repository that is a development workspace rather than a single distributable. For a developer, the interesting question is not the terminal program but anipy-api: the frontend is one consumer of it, and the README frames the split as an invitation to build your own.

A terminal front end for browsing and downloading

The stated aim is an enjoyable experience watching and downloading anime directly from the terminal, and the feature list gives a decent picture of what that means in practice. Seasonal mode groups titles by season. AniList and MyAnimeList integration means the list is not just scraped text but can be tied to the tracking databases people already use. Custom post download scripts let a user chain their own processing after a download finishes. Automatic remuxing handles container conversion. Discord presence shows what you are watching to friends.

The last item in that list is the one that separates this from a plain downloader: the README says you can use your own files instead of online anime sites. That turns the tool from a hard dependency on somebody else's server into a player and organiser for a local collection.

The project positions itself in a lineage. The credits section names ani-cli by pystardust as a heavy inspiration, and the keyword list on the package includes scraper, anime-scraper, gogoanime, beautifulsoup and requests-library-python, which describes the implementation approach honestly: HTML is fetched and parsed.

The repository also carries a DISCLAIMER.md file, linked from the README under a Legal Disclaimer heading. For a tool whose normal mode is reading a streaming site, that file is part of the product, not an afterthought.

Getting it onto a machine with pipx, pip or nix

The README addresses the non developer audience first, with a joke about wanting a binary instead of code, and then gives the answer in one line: there is no .exe, but there is pipx. The suggested command is pipx install anipy-cli.

Beyond that, the documentation site points to a Getting Started CLI page that lists more installation options, including pip and nix, plus advice on choosing between them. The repository supports the nix route concretely: flake.nix and shell.nix are present, and an .envrc file sits at the top level for a direnv based workflow. So a distribution, a virtual environment and a declarative shell are all three plausible entry points rather than one blessed path.

For the API half of the project, the README directs developers to a separate Getting Started API page with its own instructions, and the anipy-api project on PyPI carries the version badge for that package. Two documentation paths, two packages.

Worth noticing is what is not said. The README does not list a supported operating system matrix, does not give a version number for the install command itself, and does not describe an upgrade procedure beyond pointing at the docs. If you plan to keep this on a machine for a while, the version history on the PyPI project pages is where the upgrade information lives, and the repository's own release tags give the other half of that picture.

The poe task list shows how the project is worked on

The development workflow is defined as Poetry tasks, and reading them tells you more about the project's health than any badge would. The task list is short and specific:

[tool.poe.tasks]
lint = "ruff check -e cli/src/anipy_cli api/src/anipy_api"
format = "black api/src cli/src"
polish = ["lint-fix", "format", "lint"]
docs-serve = "mkdocs serve -w api/src"
bump-version = "./scripts/bump_version.sh"

Quality control is ruff for linting with a rule selection covering the usual error classes plus naming, annotation and quote checks, and black for formatting with docformatter set to black style. The docs are mkdocs with the material theme, and mkdocstrings is used to generate API documentation from the source, served with mkdocs serve -w api/src. A bump-version task calls a shell script in scripts/, so releasing is a scripted step rather than a manual edit.

The absence is as informative as the presence. The task list has a commented out test entry, which reads as no test suite wired into the developer commands. For a library other people are invited to import, that is the notable gap, and it is one a reviewer should weigh before building a front end on anipy-api. The typing story is also partial: typer and click appear in the development group with click pinned below 8.2, and the ruff selection only requires annotations at the module level rather than everywhere.

The dependency on somebody else's markup is the real limitation

Every useful thing about anipy-cli depends on a page existing somewhere with the expected structure. The keyword list names gogoanime alongside scraper and beautifulsoup, and the tool description refers to watching and downloading anime from the terminal, which in practice means the client fetches HTML from anime sites and parses it.

That design has consequences a user should understand before depending on it. When an upstream site changes its markup, the client breaks, and the fix lands in anipy-cli rather than in your workflow. When a site is unreachable from your network or blocked, there is no fallback. When a title is missing from the source, it is simply not in the list, and the AniList or MyAnimeList integration does not change that, because those databases describe the anime rather than host the files.

The project also has a legal dimension. The DISCLAIMER.md file in the repository root exists precisely because the normal use of the tool touches third party streaming sites. Whether a particular use is permitted depends on the site and the jurisdiction, and that is not something a licence file settles. The MIT style shortcut does not apply here either, because the licence is GPL-3.0, which is significant for anyone who plans to wrap anipy-api in a closed source application.

This is also where the local file mode earns its place. Playing your own files removes the scraper from the equation entirely, and the README presents that as a first class option rather than a fallback. For a user with an existing collection, that is the mode where the tool behaves like a stable local player.

Against ani-cli, and against a plain media server

The honest comparison is with the project that inspired it and with the boring alternative of not using a dedicated tool at all.

ani-cli by pystardust is credited as a heavy inspiration, and it is a terminal anime client of the same general kind. The difference anipy-cli adds is structural rather than cosmetic: the version 3 split into anipy-cli and anipy-api turns the scraper into a reusable library, and the features list leans on that by promising MyAnimeList and AniList integration, custom post download scripts, automatic remuxing and Discord presence. Someone who only wants to browse a list in a terminal has little reason to prefer one over the other; someone who wants to write their own front end does.

The other comparison is with a local media server plus a normal browser. A Jellyfin or Plex style setup gives you a real database, transcoding, and multi device access, and it makes no promises about parsing somebody else's HTML. What it does not give you is a terminal workflow, and it requires the collection to be organised into files on disk rather than streamed from a catalogue.

The remaining honest alternative is a download client for a specific source, used with a general purpose player. That approach survives a site change, but it gives up the search, the seasonal listing and the tracking integrations that are the reason this tool exists.

For a Python developer, the fourth option is the interesting one: depend on anipy-api directly and present the data through your own interface. The README invites exactly this, and the missing test suite is the price of that invitation.

Editorial conclusion

anipy-cli suits a user who wants a keyboard driven anime list on a headless or SSH box, and a Python developer who wants to build an anime front end on top of anipy-api instead of writing a scraper. It does not suit anyone who needs guaranteed availability or a stable upstream contract, because the whole design sits on parsing third party sites, and it does not suit a workflow that requires the same catalogue to be reachable from machines without Python 3.10. Verify first by checking which sites the current release of anipy-api actually parses, then by running anipy-cli against your own local files rather than an online source, since the local file path is the one mode the project describes that does not depend on anyone else's markup.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. sdaqo/anipy-cli on GitHub