cinnamon-cli 0.2.24

CLI to search TV shows, movies & anime via TMDB/AniList, scrape m3u8 links, and play in VLC/mpv

cinnamon

Watch TV shows, movies, and anime from your terminal. Search, pick a title, and it plays in mpv or VLC.

Quick start

You'll need Python 3.10+ and either mpv or VLC.

Install

pip install cinnamon-cli
cinnamon setup

The setup wizard asks for a TMDB API key (free account), your preferred player, and a color theme.

Get a player

Please note that MacOS version has not been tested since we dont have access to a mac

Platform	mpv	VLC
Windows	scoop install mpv or download from mpv.io	videolan.org
macOS	brew install mpv	brew install --cask vlc
Linux	apt install mpv (Debian/Ubuntu)	apt install vlc
Termux	pkg install mpv	pkg install vlc

Watch a show or movie

cinnamon search "Breaking Bad"

Pick a title, pick an episode (for TV) or just play (for movies), and it plays. Anime is detected automatically:

cinnamon search "Chainsaw Man"

Movies work the same way — search returns both TV and movies, and you pick:

cinnamon search "Inception"
cinnamon watch --type movie --query "Inception"

Download episodes

Downloading needs yt-dlp. Install it together with cinnamon in one step:

pip install "cinnamon-cli[download]"

Or install yt-dlp on its own (any platform):

pip install yt-dlp

cinnamon search "Breaking Bad" -d -e 1-5

---

Commands

If you run this…	…this happens
cinnamon anime <query>	Search anime via AniList (no API key needed)
cinnamon search <query>	Find a show, pick an episode, watch it
cinnamon watch --id 123 -s 2 -e 5	Go straight to S2E5 without menus
cinnamon play-url <url>	Play any m3u8/mp4 link
cinnamon resume	Continue an interrupted download
cinnamon history	Show watch history and resume from the next unwatched episode
cinnamon history --clear	Clear all watch history
cinnamon scrapers	See available streaming sources
cinnamon install <name>	Add an optional scraper (vidsrc, torrentio)
cinnamon update	Check for and install the latest version
cinnamon config show	View your settings

Common flags

Flag	What it does
-s <N>	Season number
-e <N> or -e <start-end>	Episode or range (e.g. -e 1-10)
-d	Download instead of streaming
--scraper <name>	Force a specific scraper
--player mpv or --player vlc	Choose player
-q 720p	Pick quality (480p, 720p, 1080p, best, worst)
--info-only	Just print the stream URL

---

Scrapers (streaming sources)

Built-in (work out of the box):

Name	For
webstream	TV shows & movies from vixsrc.to and vidlink.pro (HLS)
anime	Anime from allanime.day via mp4upload

Optional (install with cinnamon install <name>):

Name	Needs
vidsrc	pip install "cinnamon[scrapers]" then playwright install chromium
torrentio	npm install (torrent playback)

cinnamon install torrentio
cinnamon config default-scraper torrentio

---

Configuration

Settings are stored in ~/.config/cinnamon/config.json (Linux/macOS/Termux) or %APPDATA%/cinnamon/config.json (Windows). Change them anytime:

cinnamon config default-player mpv
cinnamon config default-scraper webstream
cinnamon config set-api-key YOUR_KEY

---

Notes

This project is mostly vibe coded and our lazy ass didnt even write more than 300 lines. feel free to give us feedback so we can improve this project and make it as good as possible.

inspired by ani-cli