Plex Media Server

Use cliamp to stream music from Plex Media Server, including any library served by PlexAmp. Streaming uses the Plex HTTP API. You do not need extra software.

Quick start: Run cliamp setup. Enter the server URL and X-Plex-Token. The TUI checks the token and writes the [plex] block. Manual steps follow.

Prerequisites

Finding your X-Plex-Token

  1. Open Plex Web in a browser and sign in.
  2. Browse to an item in the music library.
  3. Click the ··· menu → Get Info → View XML.
  4. Copy the X-Plex-Token query parameter value from the XML page URL.

You can also follow the official Plex guide.

Configuration

Add a [plex] section to ~/.config/cliamp/config.toml:

[plex]
url   = "http://192.168.1.10:32400"
token = "xxxxxxxxxxxxxxxxxxxx"
libraries = ["Music", "Jazz"]
Key Description
url Plex Media Server base URL, including port (default 32400)
token X-Plex-Token for authentication
libraries Optional comma-separated music library names to load. If omitted, cliamp loads all music libraries. Name matching is case-insensitive.

If you access Plex remotely through app.plex.tv, use a direct server URL when remote access is enabled. You can also use the server plex.direct URL from the Plex Web address bar.

Usage

After configuration, Plex appears in the cliamp provider list.

The provider shows audio playlists and the music library under two headers:

── Playlists ──
GOOD
All Music
drums

── Albums ──
Artist - Album Title (Year)

Select a playlist or album to load its tracks. Smart playlists are included. They resolve to current server content.

Start cliamp with Plex as the default provider:

cliamp --provider plex

Or set it in configuration:

provider = "plex"

How it works

cliamp calls the Plex HTTP API to list audio playlists (/playlists) and music library albums. When you select an entry, cliamp gets its track list from the playlist-items or album-children endpoint. It then creates authenticated streaming URLs in this form:

http://<server>:32400/library/parts/<partID>/<timestamp>/file.<ext>?X-Plex-Token=<token>

These URLs serve files directly. Plex serves the original file without transcoding. cliamp handles playback through its HTTP streaming pipeline. cliamp can play MP3, FLAC, AAC, OGG, OPUS, WAV, and other supported source formats.

Troubleshooting

macOS: dial tcp ... connect: no route to host

If cliamp reports no route to host for a Plex server on the LAN, but curl works with the same URL, macOS likely denies Local Network access to the app. macOS blocks the connection before it sends a packet and reports a routing error.

Fix: Open System Settings > Privacy & Security > Local Network. Enable access for the terminal app, such as Terminal, iTerm2, or Ghostty. Then restart cliamp. If the terminal is not listed, turn an entry off and on. Or reset the permission database with tccutil reset All, then restart the terminal so macOS prompts again.

Known limitations