animesama-cli is a terminal application for browsing and watching anime from anime-sama.si. It provides catalog search, persistent watch history, and the weekly release schedule. Video playback is handled by mpv.
- Full-text search of the anime-sama catalog
- Interactive TUI built with Textual, with a standard CLI fallback
- Watch history stored in SQLite, with resume support: if you stop an episode before the end, the position is saved and replaying it continues exactly where you left off instead of jumping to the next episode (finished episodes advance as usual)
- Weekly release schedule from anime-sama
- Upcoming episodes from animecountdown.com
- French dub (VF) and Japanese audio with French subtitles (VOSTFR)
- Linux and Windows support; AUR package available for Arch Linux
- Automatic OP/ED skipping in mpv: exact opening/ending timestamps come from the AniSkip community database (resolved via MyAnimeList, with season disambiguation). The opening and ending are skipped automatically once per episode — seek back to rewatch them. A clickable
Skip OP »button also appears on the right side of the screen during the opening/ending, andsskips manually. If AniSkip doesn't know the episode, it falls back to chapter detection or a +90s jump. Customize in your mpv config:--script-opts=skip_op-auto=false,skip_op-duration=120,skip_op-key=n
Every release is automatically published to all of these package managers:
| Platform | Package manager | Install command |
|---|---|---|
| Debian / Ubuntu | apt (own repository) | sudo apt install animesama-cli |
| Fedora / RHEL | dnf (own repository) | sudo dnf install animesama-cli |
| Arch Linux | AUR | yay -S animesama-cli |
| macOS | Homebrew | brew install Miro-sh/tap/animesama |
| Any Linux / macOS | pipx (PyPI) | pipx install animesama |
| Windows | Install script | See below |
The apt/dnf packages and the Homebrew formula pull in mpv and Python automatically. With pipx, install mpv through your package manager first.
Add the GPG key and the repository, then install:
curl -fsSL https://miro-sh.github.io/animesama-cli/animesama.gpg | sudo gpg --dearmor -o /usr/share/keyrings/animesama.gpg
echo "deb [signed-by=/usr/share/keyrings/animesama.gpg] https://miro-sh.github.io/animesama-cli/apt stable main" | sudo tee /etc/apt/sources.list.d/animesama.list
sudo apt update && sudo apt install animesama-cliAdd the repository file, then install:
sudo curl -fsSL -o /etc/yum.repos.d/animesama.repo https://miro-sh.github.io/animesama-cli/rpm/animesama.repo
sudo dnf install animesama-clidnf will ask you to trust the GPG key (fingerprint 035B2D3F0897E499) on first install.
yay -S animesama-clibrew install Miro-sh/tap/animesamapipx install animesamaRun the following command in PowerShell (no administrator rights required):
irm "https://raw.githubusercontent.com/Miro-sh/animesama-cli/refs/heads/master/install_windows.bat" -OutFile install.bat; .\install.batThe script installs the application via pipx and downloads mpv. Restart your terminal after installation, then run animesama-cli.
| Command | Description |
|---|---|
animesama-cli |
Launch the TUI (falls back to CLI if Textual is not installed) |
animesama-cli --cli |
Force CLI mode |
animesama-cli naruto |
Search directly |
animesama-cli --vf naruto |
Search French dub only |
animesama-cli -c |
Show watch history (unfinished episodes show their saved position and resume from it) |
animesama-cli -cf |
History with last-episode check |
animesama-cli -p |
Weekly schedule |
animesama-cli -up |
Upcoming episodes |
animesama-cli --debug naruto |
Search with debug output |
animesama-cli -h |
Show all options |
The watch history is stored at ~/.local/share/animesama-cli/history.db and can be opened with any SQLite browser. It also stores the playback position of unfinished episodes, which is how resume works.
Details
apt / dnf:
sudo apt remove animesama-cli # Debian/Ubuntu
sudo dnf remove animesama-cli # FedoraAUR:
yay -R animesama-cliHomebrew:
brew uninstall animesamapipx (Linux and Windows):
pipx uninstall animesamaWindows (mpv installed by the script):
rd /s /q "%USERPROFILE%\AnimeSamaCLI"Old manual installs (before 1.0.7):
sudo rm /usr/local/bin/animesama-cli
rm -rf ~/animesama-cli
rm -rf ~/.local/share/animesama-venv| Category | Packages |
|---|---|
| Python | requests, beautifulsoup4, textual (optional, for the TUI), windows-curses (Windows only) |
| System | mpv, git, python3 |
Built-in Python modules used: sqlite3, re, json, sys, os, time, datetime, locale, pathlib, subprocess, asyncio.
Click to expand
Can I change or disable subtitles? No. Subtitles are embedded in the video stream.
Can I watch in French? Yes. Use --vf when searching.
Can I switch the audio language? No. The site only provides French dub and Japanese audio with French subtitles.
Can I use a different video source? No, unless you write your own scraper.
Can I use VLC? No. Only mpv is supported.
Where can I find all the options? Run animesama-cli --help.
- ani-cli: Japanese audio, English subtitles (4anime, gogoanime, allmanga). animesama-cli was inspired by this project.
- ani-skip: automatic OP/ED skipping for mpv. Our skip feature uses the same AniSkip timestamp database — credits to them and the AniSkip community.
- GoAnime: Japanese audio, Portuguese subtitles
- doccli: Japanese audio, Polish subtitles (docchi.pl)
Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or pull request. You can also join the Discord server to discuss the project.
This project only fetches publicly available content and hosts nothing itself. Users are responsible for how they use it. See DISCLAIMER.md for details.