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.

Features

• Search TMDB for movies/TV shows
• Image previews with chafa
• Playback via VidSrc, Torrentio (webtorrent), or TorBox (direct stream)
• Download media with yt-dlp (VidSrc/TorBox) or webtorrent-cli (Torrentio)
• Optional TorBox API key support
• Global HTTPS proxy flag to wrap provider requests (--proxy)
• History tracking
• Interactive fzf-based interface

Installation

Prerequisites

• 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

Install CineCLI

Using pipx (recommended)

# 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]"

Using uv (fast installer)

# 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]"

From source in a virtualenv

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with download extras (yt-dlp)
pip install ".[download]"

Building a Single-Command CLI

After installation, you'll get two commands:

• cine
• cinecli

Both provide the same functionality:

# Verify installation
cine -h

# Example search
cine search "Inception"

Update / Upgrade

pipx

• From local path install: reinstall from the repo directory

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

uv

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

Uninstall

# pipx
pipx uninstall cinecli

# uv
uv tool uninstall cine

Configuration

Run initial setup:

cine setup

You'll be prompted for:

1. TMDB API key (get from TMDB)
2. Preferred player (mpv/vlc)
3. Image preview preference
4. Webtorrent temp directory
5. TorBox API key (optional; enables TorBox Play/Download options when set)

Usage

# Search for media
cine search "Inception"

# Interactive dashboard
cine dashboard

# View history
cine history

# Play media via VidSrc/Torrentio
cine vidsrc movie 27205
cine torrentio tv 1399 -s 1 -e 1

TorBox

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

Global HTTPS Proxy

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"

Dependencies

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