> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickwheel.fm/llms.txt
> Use this file to discover all available pages before exploring further.

# Plex / Plexamp

> Mirror clickwheel playlists into a Plex music library, and pull them back.

If you run Plex, clickwheel can push the same playlists into your Plex music
library so Plexamp and Plex web see them alongside your iPod, and pull Plex
playlists back into clickwheel. It's bidirectional.

## Setup

<Steps>
  <Step title="Install the Plex extra">
    ```bash theme={null}
    pipx inject clickwheel 'clickwheel[plex]'
    ```
  </Step>

  <Step title="Configure your server">
    ```yaml title="~/.clickwheel/config.yaml" theme={null}
    plex_enabled: true
    plex_url: http://192.168.1.10:32400
    plex_library_name: Music
    ```

    Keep the token out of YAML, put it in `~/.clickwheel/.env` (mode `600`) as
    `CLICKWHEEL_PLEX_TOKEN=<your-token>`. Treat it like a password. See Plex's
    [Finding an authentication token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
    if you don't have it yet.
  </Step>

  <Step title="Verify with the doctor">
    ```bash theme={null}
    clickwheel plex doctor
    ```

    A read-only, five-stage probe: config → connect → music section → sample
    track → path remap. Each stage that fails tells you exactly what to fix.
  </Step>
</Steps>

## Push and pull

| Command                       | What it does                                  |
| ----------------------------- | --------------------------------------------- |
| `clickwheel sync-plex <name>` | Push one playlist (M3U import)                |
| `clickwheel sync-plex --all`  | Push every clickwheel playlist                |
| `clickwheel plex list`        | List Plex audio playlists (with track counts) |
| `clickwheel plex pull <name>` | Import a Plex playlist into clickwheel        |

**Push** reports `pushed` vs `resolved`; a gap means Plex hasn't scanned those
files yet, so run a Plex library scan and re-sync. Re-syncing replaces
clickwheel's managed copy but leaves a same-named playlist *you* made in Plex
alone.

**Pull** recovers playlists after a fresh install or Mac wipe. Smart playlists
are dynamic queries, so pull skips them unless you pass `--include-smart`.

<Accordion title="Path remap: when Plex sees your files at a different path">
  clickwheel and Plex can mount the same library at different paths (e.g.
  clickwheel over SMB, Plex on the NAS's local filesystem). The remap swaps one
  prefix for another:

  ```yaml theme={null}
  plex_path_remap_local: /Volumes/Public/
  plex_path_remap_plex: /share/CACHEDEV1_DATA/Public/
  ```

  Find Plex's view at **Settings → Manage → Libraries → your music library → Add
  folders**. Leave both empty when Plex runs on the same machine as clickwheel.
</Accordion>

## From Claude

You can also drive this from Claude. Set up the
[MCP server](/concepts/mcp-server), then the
[Plex tools](/reference/mcp-tools/plex) are yours.