Demo

Overview

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.

Features

• 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, and s skips 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

Installation

Every release is automatically published to all of these package managers:

The apt/dnf packages and the Homebrew formula pull in mpv and Python automatically. With pipx, install mpv through your package manager first.

Debian / Ubuntu

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-cli

Fedora / RHEL

Add 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-cli

dnf will ask you to trust the GPG key (fingerprint 035B2D3F0897E499) on first install.

Arch Linux

yay -S animesama-cli

macOS

brew install Miro-sh/tap/animesama

pipx (any distribution)

pipx install animesama

Windows

Run 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.bat

The script installs the application via pipx and downloads mpv. Restart your terminal after installation, then run animesama-cli.

Usage

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.

Uninstall

sudo apt remove animesama-cli    # Debian/Ubuntu
sudo dnf remove animesama-cli    # Fedora

yay -R animesama-cli

brew uninstall animesama

pipx uninstall animesama

rd /s /q "%USERPROFILE%\AnimeSamaCLI"

sudo rm /usr/local/bin/animesama-cli
rm -rf ~/animesama-cli
rm -rf ~/.local/share/animesama-venv

Dependencies

Built-in Python modules used: sqlite3, re, json, sys, os, time, datetime, locale, pathlib, subprocess, asyncio.

FAQ

Related projects

• 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)

Contributing

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.

Disclaimer

This project only fetches publicly available content and hosts nothing itself. Users are responsible for how they use it. See DISCLAIMER.md for details.