CineCLI - Terminal Media Browser

CineCLI is a terminal-based media browser that integrates with TMDB, VidSrc, Torrentio, and TorBox for streaming and downloading media content. image

• Search TMDB for movies/TV shows
• Image previews with chafa
• Playback via VidSrc, Torrentio (webtorrent), TorBox (direct stream), or any Stremio addon manifest
• Download media with yt-dlp (VidSrc/TorBox/addons) or webtorrent-cli (Torrentio)
• Optional TorBox API key support
• Global HTTPS proxy flag to wrap provider requests (--proxy)
• History tracking with cine continue resumption (next episode, season rollover)
• Watchlist, trending, popular and top-rated browsing
• Hierarchical navigation: Escape goes back a level, Ctrl+C quits
• Interactive fzf-based interface (numbered-list fallback when fzf is missing)

• Python 3.10+
• External tools:

  # Debian/Ubuntu
  sudo apt-get install fzf mpv chafa
  # Windows
  # Chocolatey
  choco install -y mpv fzf chafa
  # Scoop
  scoop bucket add extras && scoop install mpv fzf chafa
  # macOS (IINA for GUI playback)
  brew install iina # Optional: GUI player via `open -a IINA`
  # webtorrent-cli
  npm i -g webtorrent-cli
  # yt-dlp (inside virtualenv)
  pip install yt-dlp

# From the project root
pipx install .
# Or include downloader extra (installs yt-dlp)
pipx install ".[download]"
# Verify
cine -h

Install directly from GitHub :

pipx install git+https://github.com/NerdBaba/cinecli.git
pipx install "git+https://github.com/NerdBaba/cinecli.git#egg=cinecli[download]"

# Install as a standalone tool (adds `cine` to your PATH)
uv tool install .
# Or with extras
uv tool install ".[download]"
# Verify
cine -h

Install directly from GitHub:

uv tool install git+https://github.com/NerdBaba/cinecli.git
uv tool install "git+https://github.com/NerdBaba/cinecli.git#egg=cinecli[download]"

# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install with download extras (yt-dlp)
pip install ".[download]"

After installation, you'll get two commands:

• cine
• cinecli

Both provide the same functionality:

# Verify installation
cine -h
# Example search
cine search "Inception"

• From local path install: reinstall from the repo directory

# run inside the repo directory
pipx reinstall --force .
# or
pipx uninstall cinecli && pipx install .

• From local path install: reinstall from the repo directory

# run inside the repo directory
uv tool install --reinstall .
# or
uv tool uninstall cine && uv tool install .

# pipx
pipx uninstall cinecli
# uv
uv tool uninstall cine

Run initial setup:

cine setup

You'll be prompted for:

1. TMDB API key (get from TMDB)
2. Preferred player (mpv/vlc/clapper/iina)
3. Image preview preference
4. Webtorrent temp directory
5. TorBox API key (optional; enables TorBox Play/Download options when set)
6. Stremio addons (optional; any manifest.json URL — MediaFusion, Comet, KnightCrawler, ...)
7. Subtitle language(s) (optional; e.g. en, en,fr, all)
8. Proxy prefix (optional; for blocked regions)

# Search for media
cine search "Inception"
# Interactive dashboard
cine dashboard
# Resume playback from the last verified play (next episode for series)
cine continue
cine continue --clear # clear saved progress
# View history / purge it
cine history --limit 50
cine history --clear
# Watchlist management
cine watchlist list
cine watchlist add 27205 --type movie
cine watchlist remove 27205 --type movie
cine watchlist clear
# Trending (flags skip the interactive picker)
cine trending # interactive window picker
cine trending --type movie --window day
# Popular / top-rated browsing
cine popular --type tv
cine top-rated --type movie
# Direct stream lookup / play
cine vidsrc movie 27205
cine torrentio tv 1399 -s 1 -e 1
cine torrentio movie 27205 --json # JSON output, no launch
cine torbox movie 27205 # requires TorBox API key
cine torbox tv 1399 -s 1 -e 1 --json
# Play/download via a configured Stremio addon by name
cine addon play MediaFusion movie 27205
cine addon download Comet tv 1399 -s 1 -e 1

Every verified launch (the player stayed open) is saved as a resume point. ▶ Continue appears at the top of the dashboard and cine continue works standalone: for series it picks up at the next episode — same season, or episode 1 of the next season after a finale.

Configure any number of addons during cine setup (manifest URLs). Each shows up as Play with <name> / Download with <name> in the action menu and is addressable from the CLI via cine addon play|download <name> <movie|tv> <tmdb_id> [-s N -e N].

• Escape goes back one level (episode → season → item list → dashboard).
• Ctrl+C quits immediately from anywhere.
• The ← Back entry in each menu does the same as Escape.

• TorBox integration is available inside interactive flows (Dashboard/Search/History) when a TorBox API key is configured in setup.
• For movies and TV episodes, you'll see additional actions: "Play with TorBox" and "Download with TorBox". These use direct streaming URLs and yt-dlp for downloads.
• Direct CLI access: cine torbox <movie|tv> <tmdb_id> [-s N -e N] [--json].

All respect XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_CACHE_HOME.

Wrap provider requests (VidSrc, Torrentio, TorBox) via a proxy that accepts a destination URL parameter.

# Opens dashboard and applies proxy globally to providers
python -m cinecli --proxy "https://sudo-proxy.example.com/?destination="
# With a subcommand
python -m cinecli --proxy "https://sudo-proxy.example.com/?destination=" search "Dune"

• Python: requests, pydantic
• External: fzf, mpv/vlc/clapper/iina, chafa, webtorrent-cli, yt-dlp

uv sync # install runtime + dev deps into .venv
uv run pytest # run the test suite (tests/)

subtitle_lang in settings is applied per player:

• mpv: --slang=<lang> --sub-auto=fuzzy --sub-file-cache=auto
• VLC: --sub-language=<lang>
• IINA: --args --mpv-slang=<lang> --mpv-sub-auto=fuzzy
• Downloads via yt-dlp write and embed subs with --write-sub --embed-subs.