There is a small category of Linux tools that exist because someone got tired of opening ten browser tabs to do one thing. ani-cli is one of those tools. It is a POSIX (a family of Unix-like operating systems, which includes Linux and macOS) shell script maintained by pystardust on GitHub that lets you search for an anime, pick an episode, and stream it through mpv (a lightweight open-source media player) without ever loading a browser. The trade-off is that it scrapes a third-party streaming site under the hood, processes the responses with grep and sed, and hands the stream URL off to your media player. The ani-cli binary does not host anything. It is a smart wrapper around someone else’s catalog.
The Tecmint walkthrough of ani-cli covers the install, the dependencies, and the basic flags. Most of that is correct. What I want to add here is what the article glosses over: the practical failure modes, the parts that quietly rot, and when ani-cli is the right tool versus when it is the wrong one.
What it actually does
When you run ani-cli "your favorite show", the script searches a third-party streaming site, pipes the results through fzf (a command-line fuzzy finder, a tool that lets you type a partial match and narrows down a list interactively), and presents you with the matching titles. You pick one, pick an episode, and mpv opens the stream. There is no account, no UI, and no buffering screen beyond what mpv normally shows.
A few details that matter in practice:
- The script does not host video. It is a thin client over a catalog that ani-cli has no control over. If the upstream changes its URL structure, ani-cli breaks until the maintainer patches the script.
- Playback runs through mpv on Linux and IINA on macOS. If you do not have one of those installed, the script will not work, and the error message is not always helpful.
- The search index is not exhaustive. Some titles show up; some do not. The ones that do not are usually newer or older than the source’s coverage window.
- Downloading uses yt-dlp or ffmpeg as a fallback. The download path is more fragile than the streaming path, in my experience, because yt-dlp’s compatibility with the upstream source rotates more often than the streaming path does.
If you treat ani-cli as a convenience tool for a specific catalog rather than a replacement for a real streaming subscription, the experience is fine. If you treat it as your primary way to watch anime, you are going to hit the rough edges I describe below.
The install, briefly
On Debian 13 unstable and derivatives, sudo apt install ani-cli works. On Fedora, you need RPM Fusion enabled for mpv, then you can enable the maintainer’s COPR (a personal package repository system Fedora uses to distribute packages outside the main repos) repository and install. On Arch and Arch-based distros, yay -S ani-cli covers it. RHEL, Rocky Linux, and Ubuntu outside the Debian unstable branch do not have native packages; the source install is git clone, sudo cp ani-cli/ani-cli /usr/local/bin, and a cleanup of the cloned directory. That last method is the one most people end up using.
The dependency list is short but not optional:
- grep and sed, for processing the search results.
- curl, for fetching the catalog.
- mpv or IINA, for playback.
- fzf, for the interactive picker.
- yt-dlp, for downloads, with ffmpeg as the fallback.
- patch, only if you want to use the self-update feature.
If you are setting up a fresh Linux machine and you want to try ani-cli, this is a five-minute install on Debian and a ten-minute install on Fedora. The macOS install is its own story and not worth describing here because the script’s behavior on macOS is more brittle.
What quietly breaks
This is the part the Tecmint article does not say enough about. There are three failure modes I have hit:
- Cloudflare blocks. The upstream source sits behind Cloudflare, and Cloudflare’s bot-detection eventually flags a fresh machine’s IP after a few requests. The script stops returning results and looks broken. The fix is to wait a few hours, switch networks, or use the
--continueflag to resume after a cooldown. - Stale scripts. The script is patched every few weeks as the upstream changes its URL structure. If you installed two months ago and have not updated, your ani-cli is broken in a way that looks like a network problem.
ani-cli -U(self-update) fixes it when the upstream package supports it; otherwise, re-clone and re-install. - Episode mismatch. fzf is a fuzzy finder, and the wrong title can match when two shows share a word. Picking the wrong show is harmless but annoying. Hit Escape and re-search with a more specific query.
- mpv codec issues. On a fresh install, mpv sometimes lacks the proprietary codec needed for the upstream’s HLS (HTTP Live Streaming, an adaptive bitrate protocol used by most modern streaming sites) streams. The fix is to install the w64codecs pack or the libavcodec extras that match your distro; without them, playback returns audio but no video, which looks like a script bug and is not.
A practical mitigation is to keep the script updated and to treat any “no results” return as a stale-script symptom first and a network symptom second. Most of the time, it is the script. The codec issue is the second-most-common cause of “the player opened but nothing happened” reports on Linux, and it is the one that takes longest to diagnose if you have not seen it before.
Trade-offs
ani-cli is the right tool when you want a quick terminal-only workflow for a specific catalog and you do not mind being at the mercy of a third-party scrape. It is the wrong tool when you need reliable playback across many titles, when you cannot tolerate a 24-hour outage while the maintainer catches up to an upstream change, or when you want any kind of watchlist sync.
The official streaming services are not free, but they have SLAs (service-level agreements, the commitments a vendor makes about uptime and behavior). ani-cli is free, but its availability depends on a single maintainer and a single upstream source. That is the trade. If you are fine with the trade, ani-cli is one of the cleanest examples of the genre.
If you decide to try it, do not expect it to replace a paid service. Use it as a backup for the shows that fall outside your subscription, or as a way to sample a series before committing to it. That is the use case the script was built for, and the one where its rough edges stay manageable.
What I would tell past me
A short list, if I were setting this up again.
- Install fzf first, before you clone ani-cli. fzf is the dependency most people skip and then wonder why the picker is broken.
- Run
ani-cli -U(self-update) once a month. Most of the breakage I have hit was a stale script, not a real outage. - If you get “no results” on a title you know exists, check the upstream before debugging your network. The script is the more likely culprit.
- Treat the download path as a convenience, not a primary workflow. The streaming path is more reliable than the download path by a wide margin.