📺 cli-tv

July 4, 2026 · View on GitHub

A blazing fast, lightweight terminal IPTV browser and player built in Rust.

cli-tv lets you seamlessly browse, search, filter, and stream thousands of publicly available live channels from the iptv-org project without ever leaving your terminal. Powered by a fluid, keyboard-driven Ratatui interface, it delegates high-performance, stutter-free playback to mpv.

cli-tv screenshot

✨ Features

⚡ Zero-Lag UI: Background synchronization and health probing ensure the interface never blocks on network I/O.
🔍 Fuzzy Search: Context-aware, ultra-fast fuzzy matching over channel names, alternative titles, countries, and categories powered by nucleo-matcher.
📊 Live Health Status: Active stream probing dynamically flags streams in your list (● Live, ◐ Slow, ○ Dead, • Unconfirmed).
⭐ Favorites & History: Instantly bookmark (f) your frequent streams, backed by a persistent local SQLite cache.
🎨 Modern TUI Styling: Beautiful phosphor color palette with truecolor support, an automatic 256-color fallback, and a high-contrast accessibility variant.
🛠️ Guided Player Setup: Built-in interactive setup hooks your local package manager to fetch mpv dynamically if it isn't found in your runtime path.

🏗️ Architecture & Data Flow

cli-tv is structured as a robust Cargo workspace, isolating concerns into small, single-responsibility crates for peak reliability and testability:

cli-tv (bin): The thin CLI entry point that handles argument parsing and initializes the event loop.
ui: Evaluates the terminal-safe event loop, manages the state machine, and renders responsive Ratatui widgets.
data: Orchestrates concurrent upstream syncing (channels, streams, countries, blocklists), caches data using SQLite, and manages async stream health probing.
player: Manages environment path detection, provides guided binary configuration, and fires target hooks asynchronously with secure header passthroughs.
core: Contains pure domain models and fuzzy-search criteria with no internal I/O side effects.

🚀 Installation & Setup

📦 Option 1: Download Pre-compiled Binaries (Recommended)

Grab the latest optimized release built automatically via GitHub Actions for your specific platform on the Releases Page.

Supported targets include:

Linux: x86_64 (GNU/MUSL), aarch64 (GNU)
macOS: x86_64 (Intel), aarch64 (Apple Silicon)
Windows: x86_64 (MSVC)

🛠️ Option 2: Build from Source

If you prefer building locally, ensure you have Rust 1.74 or newer installed:

# Clone the repository
git clone [https://github.com/webwurst9000/cli-tv.git](https://github.com/webwurst9000/cli-tv.git)
cd cli-tv

# Run with cached data
cargo run --release

# Force a clean sync from upstream on startup
cargo run --release -- --refresh

🎬 Interactive `mpv` Auto-Detection

The media player mpv is required for video stream playback. If mpv is missing from your system PATH, cli-tv features a built-in guided setup. It will safely detect your operating system environment, display the correct system installation command, and offer to run it for you:

macOS: Installs via Homebrew (brew install mpv)
Linux: Installs via your native package manager (apt, dnf, or pacman)
Windows: Installs via Windows Package Manager (winget install mpv)

⚠️ Note: cli-tv never installs dependencies silently. It will explicitly show you the command and wait for confirmation before interacting with your terminal environment.

⌨️ Keybindings & Flags

cli-tv uses intuitive, Vim-inspired keybindings to keep your hands on the home row.

Key	Action
`Tab`	Switch focus between the Sidebar and the Channel List
`h` / `l` or `←` / `→`	Explicitly focus Sidebar (left) or Channel List (right)
`j` / `k` or `↓` / `↑`	Move selection up or down within the active pane
`b`	Toggle sidebar visibility entirely (ideal for narrow windows)

Filtering & Browsing

Key	Action
`c` / `g`	Switch sidebar taxonomy to Countries or Categories
`[` / `]`	Cycle through open sidebar tabs
`1` - `9`	Jump directly to the $N$ -th category and apply it as a filter
`Enter`	Apply sidebar selection as a filter, or play a highlighted channel
`x`	Clear all active country and category filters

Search, Playback & Favorites

Key	Action
`/`	Open contextual fuzzy search (filters whichever pane is focused)
`Esc`	Close search input / clear ongoing text filter
`f`	Toggle favorite status (★) on the selected channel
`?`	Toggle the built-in, full-screen keybindings help overlay
`q`	Safely clean up background processes and close `cli-tv`

Command-Line Arguments

Tailor the application runtime by appending these flags upon launch:

--refresh: Forces an immediate local cache update from upstream APIs.
--no-health-check: Disables background async stream health URL probing.
--debug: Outputs comprehensive, daily-rotating trace logs to your platform's XDG state directory.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.