Metadata-Version: 2.4
Name: plextool
Version: 3.2.0
Summary: Maintenance helpers for a Plex Media Server
Author: Milkmansson
License-Expression: MIT
Project-URL: Homepage, https://github.com/milkmansson/plextool
Project-URL: Documentation, https://plextool.readthedocs.io/
Project-URL: Source, https://github.com/milkmansson/plextool
Project-URL: Issues, https://github.com/milkmansson/plextool/issues
Keywords: plex,plex-media-server,plexapi,recently-added,duplicates,watched,subtitles,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: plexapi>=4.18
Requires-Dist: pyjwt[crypto]
Provides-Extra: qr
Requires-Dist: segno; extra == "qr"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: segno; extra == "dev"
Dynamic: license-file

# plextool

> [!WARNING]
> Still in development/testing... please raise an issue if one is found!

Swiss army knife command line tool for Plex library maintenance. Built on [python-plexapi](https://python-plexapi.readthedocs.io/), which talks to the
server through its API.  No accesses is made to the Plex database file which is too risky to edit by hand.

## What it is useful for

plextool is a CLI toolkit for looking after a Plex Media Server: fixing things Plex's web interface can't, giving CLI methods to things that would otherwise need many clicks through the web interface for, for server maintenance over SSH, and for finding and fixing problems in large libraries.  Typical jobs:

- **Fix the Recently Added order.** This is what it was first built for. Plex has no way to
  edit the Recently Added lists, so after the database is rebuilt, duplicate
  files are deleted and Plex rescans, or files are reorganised on disk, everything shows up as
  "new" and the real newest content is buried. [`plextool recent`](https://plextool.readthedocs.io/en/latest/commands/recent.html)
  changes the "added at" date of movies, shows, seasons and episodes: set each
  item back to its own release or air date, shift dates by an offset, or set one date for a
  whole batch. The date is locked so a rescan can't undo it.
  ```console
  $ plextool recent --recent 20 --release              # preview: put the 20 newest back to their release dates
  $ plextool recent --title "Some Show" --shift=-30d --commit
  ```
- **Manage who has access.** [`plextool users`](https://plextool.readthedocs.io/en/latest/commands/users.html) lists who can use the server, invites people, changes
  what they can see and removes them, with a preview of exactly what would be granted or lost.
- **Tidy the apps authorised on the account.** [`plextool devices`](https://plextool.readthedocs.io/en/latest/commands/devices.html) lists every app and device signed in
  to the Plex account and removes the old ones by ID, age, app or name. It never removes a Plex Media Server.
- **Give another tool its own token.** [`plextool token`](https://plextool.readthedocs.io/en/latest/commands/token.html) makes, lists and revokes tokens for a program such as a Plex MCP
  server, so it does not need the saved login. Whether it is full access (`--rw`) or a shared user's (`--ro`)
  has to be stated, and the output says what the token can do.
- **Find and remove duplicate movies and episodes.** [`plextool dupes`](https://plextool.readthedocs.io/en/latest/commands/dupes.html)
  lists every item Plex holds more than one file for, and can delete the extras that are not wanted.
- **Free up disk space.** [`plextool stale`](https://plextool.readthedocs.io/en/latest/commands/stale.html) finds large, never-watched or
  long-idle movies and shows.
- **Look up an item, or compare several.** [`plextool info`](https://plextool.readthedocs.io/en/latest/commands/info.html) shows what Plex holds about a movie, show
  or episode: the people, the tags and IDs, and the technical side (paths, video, audio and subtitle
  tracks). Giving more than one item shows them side by side with the differences marked.
- **Audit a library.** [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) reports unmatched items, missing files,
  missing posters or summaries, low-resolution video, and missing subtitle or audio languages.
- **Copy, back up and restore watched status.** [`plextool watched`](https://plextool.readthedocs.io/en/latest/commands/watched.html) moves watched
  state between users (for example when a shared account is split), saves it to a file, and
  restores it after a rebuild or when someone closes and reopens their Plex account.
- **Clear a stuck Continue Watching list.** [`plextool resume`](https://plextool.readthedocs.io/en/latest/commands/resume.html) lists and removes
  entries that won't go away.
- **Back up and restore playlists.** [`plextool playlists`](https://plextool.readthedocs.io/en/latest/commands/playlists.html) saves video playlists
  to a file and recreates them on the same or another server.
- **Get subtitles.** [`plextool subs`](https://plextool.readthedocs.io/en/latest/commands/subs.html) extracts the subtitle tracks inside MKV and MP4
  files, searches Plex's subtitle providers for a language and downloads one, and, with
  `--export`, copies the subtitle Plex downloaded out of its database into a file beside
  the video so it works outside Plex too. Plex itself never writes that file.
- **Script Plex.** Reports can print JSON, and exports can go through a pipe, so the output
  feeds other tools.

> [!IMPORTANT]
> Everything that changes the server is a preview until `--commit` is passed. plextool uses Plex's API and
> never edits the Plex database file. It signs in through a browser with
> [`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html), and works against a server on the same machine, across the
> internet, or directly with no internet access ([`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html)).

## Commands

| Command | What it does |
| --- | --- |
| [`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html) | Sign in to Plex with a link or QR code, list and remove old sign-ins from the account, and wipe the saved login and keys. |
| [`plextool users`](https://plextool.readthedocs.io/en/latest/commands/users.html) | See who has access to the server, and invite, change and remove people: libraries, restrictions, downloads, invitations. Previews until `--commit`. |
| [`plextool devices`](https://plextool.readthedocs.io/en/latest/commands/devices.html) | List the apps and devices authorised on the Plex account, and sign out the ones no longer wanted, by ID or by age, app or name. Plex Media Servers are never removed. |
| [`plextool token`](https://plextool.readthedocs.io/en/latest/commands/token.html) | Make, list and revoke tokens for other tools (such as an MCP server) without sharing the saved login: a separate full-access token that can be revoked on its own, or a shared user's token. Also shows who has access to the server. |
| [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on the account or network and choose the one to use. Covers working offline or directly against the server. |
| [`plextool status`](https://plextool.readthedocs.io/en/latest/commands/status.html) | Server version, library sizes, who is watching what. |
| [`plextool info`](https://plextool.readthedocs.io/en/latest/commands/info.html) | Everything Plex holds about one item: people, tags, playback, and every file, path, video, audio and subtitle track. Several items can be compared side by side. |
| [`plextool scan`](https://plextool.readthedocs.io/en/latest/commands/scan.html) | Scan libraries or a single folder, refresh metadata, empty trash, optimize. |
| [`plextool recent`](https://plextool.readthedocs.io/en/latest/commands/recent.html) | Change "added at" dates to reorder Recently Added. Works on movies, shows, seasons and episodes. |
| [`plextool dupes`](https://plextool.readthedocs.io/en/latest/commands/dupes.html) | List movies and episodes that have more than one file, and optionally delete the extras. |
| [`plextool stale`](https://plextool.readthedocs.io/en/latest/commands/stale.html) | Find large, unwatched or long-idle content to free up space. |
| [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) | Find unmatched items, missing files, missing posters or summaries, low resolution, missing subtitle or audio languages. |
| [`plextool watched`](https://plextool.readthedocs.io/en/latest/commands/watched.html) | Copy watched state between users, back it up and restore it, or mark a show or movie watched. |
| [`plextool resume`](https://plextool.readthedocs.io/en/latest/commands/resume.html) | List or clear stuck Continue Watching entries. |
| [`plextool playlists`](https://plextool.readthedocs.io/en/latest/commands/playlists.html) | Back up and restore video playlists. |
| [`plextool subs`](https://plextool.readthedocs.io/en/latest/commands/subs.html) | Extract subtitles from MKV and MP4 files, search Plex's subtitle providers for new ones and pick which to download, and copy subtitles Plex downloaded (kept in its database, not beside the video) out as files next to the video. Files are named for Plex, forced and SDH included. |

The `plextool` commands that change anything do a dry run unless `--commit` is
passed. Deleting files (`dupes --keep`) also asks for `DELETE` to be typed.

## Quick start

Install it from PyPI. This needs `python` installed as a prerequisite:

```console
$ python3 -m venv .venv && source .venv/bin/activate   # optional: keeps plextool's packages separate
$ pip install 'plextool[qr]'        # '[qr]' adds a QR code to the sign-in; leave it off if no QR code is wanted
$ plextool auth login               # open the link it prints (or scan the QR code) and approve
$ plextool server find              # servers on the Plex account and on the network
$ plextool server use "My Server"   # one of the names from the list
$ plextool status                   # libraries, and who is watching what right now
```

`status` ends with what is playing:

```console
Now playing (1 session, 0 transcoding)
  alice: Some Movie (2020) [playing] on Living Room TV
```

To get, say, Swedish subtitles for that movie from the subtitle providers Plex searches:

```console
$ plextool subs fetch -t "Some Movie" --lang sv --list               # see what is available; nothing is downloaded
$ plextool subs fetch -t "Some Movie" --lang sv --choose --commit    # pick one; Plex downloads it
$ plextool subs fetch -t "Some Movie" --lang sv --choose --export --commit   # same, and also save a file beside the video
```

**Where the subtitle ends up.** When Plex downloads a subtitle from a provider, it keeps
the copy in its own database. It does not put a file next to the video, so only Plex can
show it: another player, or another Plex server, never sees it. The first two commands stop
there, and the subtitle is picked from the player's subtitle menu.

**`--export` gets around that.** Once Plex has downloaded the subtitle, plextool copies
Plex's stored copy out of the server and saves it as an ordinary file beside the video
(`<video name>.sv.srt`), which any player can use. It doesn't read the video file, so the
MKV or MP4 is never opened, and it doesn't contact the subtitle provider. (Subtitle
tracks that are already inside an MKV or MP4 are a different job, for `plextool subs extract`.)
For `--export`, the machine it runs on must be able to read the media files. If it sees
them under a different path than Plex does, use `--map`. The
[`subs` page](https://plextool.readthedocs.io/en/latest/commands/subs.html#where-each-subtitle-comes-from) sets out where each kind of subtitle comes from.

For a TV show, `-t "Some Show"` covers every episode, which is a search for each one,
so start with `--list`.

If the server is on the same machine as the terminal, skip `server find` and `server use`:
plextool tries `http://localhost:32400` by default. Without internet access, see
[working offline](https://plextool.readthedocs.io/en/latest/commands/server.html#working-offline-or-directly-against-the-server).

## Getting help

Every command explains itself, with options and examples:

```console
$ plextool --help
$ plextool recent --help
$ plextool watched copy --help
```

To see what plextool is doing, add `-v` (`--verbose`) to any command. It prints each request sent
to Plex, with the time, on standard error, followed by a line for the reply: the status, how many
records were in it (and where that page sits in the whole list), its size and how long it took.
It also prints when each slow step starts and finishes. The token
is hidden in that output.

```console
$ plextool stale --all-users -v
```

When a command takes more than 5 seconds, plextool prints `Finished in 2m 14s` on standard error at the end
(with `-v`, always).

Reading a big library can take minutes. After about 10 seconds of silence, plextool prints
`still reading <library>...` to standard error, and again every 20 seconds, so it is clear it has not
stopped. `--json` output is not affected.

A fuller page for each command is on [Read the Docs](https://plextool.readthedocs.io/)
(linked in the table above); its source is in `docs/source/commands/`.

## Install

plextool needs Python 3.10 or later, because plexapi 4.18 does. It is tested on
Python 3.12. If something doesn't work on another version, please
[open an issue](https://github.com/milkmansson/plextool/issues) with the Python
version.

`plextool subs` also needs MKVToolNix (`mkvmerge`, `mkvextract`) for MKV files and
FFmpeg (`ffmpeg`, `ffprobe`) for MP4 files. Only the ones for the file types
in use are needed.

```console
$ pip install plextool     # installs the `plextool` command
$ plextool --help
```

To install from a checkout instead (this needs `git`):

```console
$ git clone https://github.com/milkmansson/plextool.git
$ cd plextool
$ pip install .
```

To run from a checkout without installing, `pip install -r requirements.txt`
and use `python3 -m plextool ...` instead.

## Connecting

Sign in once. This prints a link (and a QR code, if `segno` is installed) to
approve in a browser:

```console
$ plextool auth login
$ plextool server find                       # skip if the server is on this machine
$ plextool server use "My Server"            # or: server use http://myserver:32400
```

Without a saved choice, plextool uses `http://localhost:32400`, or `$PLEX_URL`
or `--base-url` if given. [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) explains the
options, including working with no internet or directly on the server's machine.

That saves a Plex token in `~/.config/plextool/` (readable only by the current user).
[`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html) explains exactly what is kept, how to wipe it
with `plextool auth wipe`, and `--type jwt`, a short-lived token that plex.tv
accepts but Plex Media Server doesn't yet.

plextool looks for a [Plex token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
in this order: `--token`, `--token-file FILE` (`-` for
standard input), `$PLEX_TOKEN`, the output of `$PLEX_TOKEN_CMD`, then the saved
login. Prefer `--token-file` or the environment to `--token`, which leaves the
token in the shell history.

## Development

```console
$ pip install -e '.[dev]'
$ pytest
```

## Disclaimer

These tools only use the documented plexapi calls, but they do write to the
server when `--commit` is passed. Check the dry run first. Use is at the user's own risk.
