GoplexCLI

A powerful, fast, and elegant command-line interface for browsing and streaming media from your Plex server.

Features

• Browse Media: Quickly browse your entire Plex library using fzf's fuzzy finder
• Multi-Select: Select multiple items with TAB for batch downloads or sequential playback
• Download Queue: Add items to a persistent queue for batch downloads later
• Rich Previews: View detailed metadata in the preview window
• Stream with MPV: Watch movies and TV shows directly with MPV player
• Download with Rclone: Download media files to your local system with beautiful progress bars
• Remote Streaming: Publish streams for playback on other devices via mDNS discovery
• Smart Caching: Cache your media library locally for instant browsing
• Multi-Server Support: Connect to and manage multiple Plex servers
• Media Type Filtering: Filter by Movies, TV Shows, or browse all media
• Cross-Platform: Works on macOS, Linux, and Windows
• Beautiful UI: Built with Charm libraries for a polished terminal experience

Prerequisites

Before using GoplexCLI, ensure you have the following installed:

• Go 1.20+ (for building from source)
• fzf - Fuzzy finder for browsing media
  • macOS: brew install fzf
  • Linux: sudo apt install fzf or sudo pacman -S fzf
  • Windows: choco install fzf
• mpv - Media player for streaming
  • macOS: brew install mpv
  • Linux: sudo apt install mpv or sudo pacman -S mpv
  • Windows: Download from mpv.io
• rclone - For downloading media files
  • macOS: brew install rclone
  • Linux: sudo apt install rclone or download from rclone.org
  • Windows: Download from rclone.org

Installation

From Source

git clone https://github.com/joshkerr/goplexcli.git
cd goplexcli
make build

This builds both goplexcli (main application) and goplexcli-preview (preview helper).

Then install to your PATH:

# Using make (installs to /usr/local/bin)
make install

# Or manually
sudo cp goplexcli goplexcli-preview /usr/local/bin/

# Or add project directory to PATH
export PATH="$PATH:/path/to/goplexcli"

Quick Start

1. Login to Plex

First, authenticate with your Plex account:

goplexcli login

You'll be prompted for your Plex username and password. Your credentials are used only for authentication and the resulting token is saved securely in your config directory.

2. Build Media Cache

Index your media library:

goplexcli cache reindex

This will fetch all your movies and TV shows from your Plex server and cache them locally for fast browsing.

3. Browse and Play

Launch the media browser:

goplexcli browse

This will open fzf with your entire media library. Use the arrow keys or type to search, then:

• Press TAB to select/deselect items (multi-select mode)
• Press Enter to confirm selection
• Choose Watch to stream with MPV locally (plays sequentially if multiple items)
• Choose Download to download with rclone (downloads all selected items)
• Choose Stream to publish for remote playback on other devices (uses first item only)

Commands

goplexcli login

Authenticate with your Plex account and save credentials.

goplexcli login

goplexcli browse

Browse and play media from your Plex server.

goplexcli browse

Features:

• Select media type (Movies, TV Shows, or All)
• Fuzzy search across your entire library
• Multi-select with TAB - Select multiple items for batch operations
• Press Ctrl+P to toggle preview window with:
  • Year, rating, duration
  • Plot summary
  • File path
• Press Enter to confirm selection
• Choose Watch to stream locally (creates playlist if multiple items), Download to save all, Add to Queue to save for later, or Stream to publish for remote playback

Multi-Select Examples:

# Select multiple episodes of a TV show
goplexcli browse
# Select "TV Shows"
# Search for "Breaking Bad"
# Press TAB on episodes 1, 2, 3
# Press Enter
# Choose "Watch" - plays all episodes sequentially

# Batch download movies
goplexcli browse
# Select "Movies"
# Press TAB on multiple movies
# Press Enter
# Choose "Download" - downloads all selected files

Using the Download Queue:

The queue lets you collect items across multiple browsing sessions and download them all at once:

# Add items to the queue
goplexcli browse
# Select media, press Enter
# Choose "Add to Queue"

# Later, view and download the queue
goplexcli browse
# Select "View Queue" from the media type menu
# Choose "Download All" to download everything in the queue

Queue features:

• Persistent: Queue survives between sessions
• Concurrent-safe: Multiple instances can safely add to the queue while another downloads
• Deduplication: Same item won't be added twice
• Manage items: Remove individual items or clear the entire queue

goplexcli stream

Discover and play streams published by other devices on your local network.

goplexcli stream

How it works:

Publishing a stream (Mac/Desktop):

1. Run goplexcli browse, select media, and choose Stream
2. Server starts on port 8765 and announces via mDNS
3. Displays a URL like http://192.168.1.5:8765 for easy access

Consuming streams:

Option 1: Web UI (iPad/iPhone/Any Browser)

• Open the displayed URL in Safari/Chrome
• See all available streams in a mobile-friendly interface
• Tap "Play in Infuse/VLC/Plex" to launch your favorite player

Option 2: CLI (Mac/Linux)

• Run goplexcli stream to discover servers
• Select a stream to play in MPV

Use cases:

• Browse your library on Mac, watch on iPad via web UI
• Queue up content from laptop for TV playback
• Share streams between devices without re-browsing the library

Supported Players:

• Infuse (iOS/tvOS) - Deep link support
• VLC (iOS/Android/Desktop)
• Plex (iOS/Android/Desktop)
• MPV (via CLI on desktop)

goplexcli cache

Manage your local media cache.

Update Cache

Update the cache with new media (incremental):

goplexcli cache update

Rebuild Cache

Rebuild the entire cache from scratch:

goplexcli cache reindex

Cache Info

View cache statistics:

goplexcli cache info

Search Cache

Search for media in your cache:

goplexcli cache search "movie title"

goplexcli server

Manage multiple Plex servers.

List Servers

List all configured servers:

goplexcli server list

Enable/Disable Servers

Enable or disable specific servers:

goplexcli server enable <server-name>
goplexcli server disable <server-name>

goplexcli config

Display current configuration:

goplexcli config

Configuration

Configuration files are stored in platform-specific directories:

• macOS: ~/.config/goplexcli/
• Linux: ~/.config/goplexcli/ or $XDG_CONFIG_HOME/goplexcli/
• Windows: %APPDATA%\goplexcli\

Config File Structure

The config.json file contains:

{
  "servers": [
    {
      "name": "My Plex Server",
      "url": "http://your-plex-server:32400",
      "token": "your-auth-token",
      "enabled": true
    }
  ],
  "plex_username": "your-username",
  "mpv_path": "mpv",
  "rclone_path": "rclone",
  "fzf_path": "fzf"
}

The config supports multiple servers. You can manually edit this file to set custom paths for mpv, rclone, or fzf if they're not in your PATH.

How It Works

Media Caching

GoplexCLI caches your media library locally to enable fast, offline browsing with fzf. The cache stores:

• Movie titles, years, and metadata
• TV show names, season and episode numbers
• File paths for streaming and downloading
• Rclone remote paths (automatically converted from Plex paths)

Cache Location:

• macOS/Linux: ~/.config/goplexcli/cache/media.json
• Windows: %APPDATA%\goplexcli\cache\media.json

Rclone Path Conversion

GoplexCLI automatically converts Plex file paths to rclone remote paths. For example:

Plex Path:

/home/joshkerr/plexcloudservers2/Media/TV/ShowName/Season 01/Episode.mkv

Rclone Path:

plexcloudservers2:/Media/TV/ShowName/Season 01/Episode.mkv

The conversion:

1. Removes the /home/joshkerr/ prefix
2. Adds a : after the remote name (e.g., plexcloudservers2)

Streaming

When you choose to watch a media item, GoplexCLI:

1. Requests a direct stream URL from your Plex server
2. Launches MPV with the stream URL
3. MPV handles the playback with seeking and buffering

Downloading

When you choose to download a media item, GoplexCLI:

1. Extracts the rclone remote path from the cached media
2. Uses rclone to copy the file to your current directory
3. Displays a progress bar during download (via rclone-golib)

Troubleshooting

"fzf not found"

Install fzf using your package manager (see Prerequisites).

"mpv not found"

Install mpv using your package manager (see Prerequisites).

"rclone not found"

Install rclone and ensure it's configured with your remotes:

rclone config

"Cache is empty"

Run goplexcli cache reindex to build your media cache.

"Preview binary not found"

Ensure both binaries are installed:

make build
make install
# Or add the project directory to your PATH

Authentication Issues

If you're having trouble logging in:

1. Verify your Plex username and password
2. Check that your Plex server is accessible
3. Try manually editing ~/.config/goplexcli/config.json with your server URL and token

Stream Discovery Issues

CLI discovery (goplexcli stream) not working:

1. Ensure both devices are on the same local network
2. Check firewall allows mDNS (port 5353 UDP) and HTTP (port 8765 TCP)
3. On the publishing device, verify the stream server started successfully
4. Try the web UI instead: http://<publisher-ip>:8765

Web UI not accessible:

1. Get the IP address shown when you published the stream
2. Ensure devices are on the same network
3. Check firewall allows port 8765 TCP
4. Try accessing directly: http://<ip>:8765
5. On iOS, ensure you're not using cellular data

Deep links not working on iOS:

1. Ensure you have Infuse, VLC, or Plex installed
2. If the link doesn't open, copy the stream URL and paste into your player manually
3. Some players require you to tap-and-hold the link, then choose "Open in [App]"

Project Structure

goplexcli/
├── cmd/
│   ├── goplexcli/
│   │   └── main.go          # Main CLI application
│   └── preview/
│       └── main.go          # Preview helper for fzf
├── internal/
│   ├── cache/
│   │   └── cache.go         # Media caching logic
│   ├── config/
│   │   └── config.go        # Configuration management
│   ├── download/
│   │   └── download.go      # Rclone download integration
│   ├── player/
│   │   └── player.go        # MPV player integration
│   ├── plex/
│   │   └── client.go        # Plex API client
│   ├── queue/
│   │   └── queue.go         # Persistent download queue
│   ├── stream/
│   │   └── server.go        # Stream server and mDNS discovery
│   └── ui/
│       └── fzf.go           # fzf integration
├── Makefile                 # Build automation
├── go.mod
├── go.sum
├── .gitignore
└── README.md

Dependencies

• LukeHagar/plexgo - Plex API SDK
• charmbracelet/lipgloss - Terminal styling
• charmbracelet/bubbletea - TUI framework
• spf13/cobra - CLI framework
• joshkerr/rclone-golib - Rclone integration with progress bars
• gofrs/flock - Cross-platform file locking
• golang.org/x/term - Secure terminal input

External Tools:

• fzf - Fuzzy finder
• mpv - Media player
• rclone - Cloud storage sync

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - See LICENSE file for details

Acknowledgments

• Built with Charm libraries for beautiful terminal UIs
• Plex API integration via plexgo
• File downloads via rclone-golib