Skip to Content
Overview

plexctl

A robust Plex CLI and TUI written in Go

plexctl logo

plexctl is designed for users who want a powerful, terminal-based way to interact with their Plex Media Server. Whether you prefer a rich interactive interface (TUI) or quick command-line actions, plexctl has you covered.

Demo

plexctl TUI Demo

Key Features

  • 🚀 Interactive TUI: Navigate libraries, browse media, and manage sessions in a full-screen terminal app.
  • Friends Libraries: Browse and search your friends’ shared libraries from the left sidebar while keeping your own server selected.
  • 🔍 Fuzzy Search: Instantly find movies, shows, or episodes with global fuzzy search.
  • 🎬 Integrated Playback: Launch media directly in mpv with full control.
  • ⚙️ Deep Configuration: Manage library visibility, custom icons, and theme preferences.
  • 🛠️ Power-User CLI: Scriptable commands for status, reindexing, and metadata retrieval.
  • 🎨 Theme Support: Multiple color schemes and icon sets (Emoji, Nerd Fonts, ASCII).

Getting Started

Installation

Download the latest binary for your platform from the GitHub Releases  page.

Manual Installation (macOS/Linux)

If you download the binary directly, you will need to make it executable and move it to your path:

# Rename the downloaded binary (example for macOS ARM)
mv plexctl_Darwin_arm64 plexctl
 
# Make it executable
chmod +x plexctl
 
# Move to a directory in your PATH (optional)
sudo mv plexctl /usr/local/bin/

If you have Go installed:

go install github.com/ygelfand/plexctl@latest

Prerequisites

mpv is required for media playback. Before starting the TUI or a player, plexctl checks for missing or outdated mpv and offers installation with your approval. You can also run plexctl mpv or plexctl mpv install explicitly. On Debian/Ubuntu, an outdated apt candidate triggers an offer to build the latest stable release from source. The pre-check shows required and missing development packages, including Meson from apt, FFmpeg, libass, Lua, and libsixel. Dependency installation and compilation require your approval. A compatible libplacebo is used from apt or built as a static Meson subproject. The build enables Sixel and Lua and verifies the video outputs before activation.

Source builds install under ~/.local/opt/plexctl-mpv-<version>-<build-id> and activate through ~/.local/bin/mpv, preserving the previous file or symlink. Put ~/.local/bin first on PATH for future shells; plexctl prints instructions when needed. Logs and sources stay in the plexctl cache. Other package managers verify the version after installation. For installation outside this setup flow:

  • macOS: brew install mpv
  • Debian/Ubuntu: plexctl mpv install (builds from source when apt is too old)
  • Other Linux: Use your package manager, such as sudo pacman -S mpv
  • Windows: Download from mpv.io 

Usage

Simply run plexctl to launch the interactive TUI. On first run, it will guide you through authentication and server selection.

# Launch TUI
plexctl
 
# Search via CLI
plexctl search find "Matrix"
 
# Check index status
plexctl search status
 
# Play media via CLI
plexctl play 12345
 
# Play in terminal video mode
plexctl play 12345 --tct

Check out the CLI Reference for a full list of commands.

Last updated on
TUI Guide