plextool 3.0.1__tar.gz → 3.1.1__tar.gz

{plextool-3.0.1 → plextool-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plextool
-Version: 3.0.1
+Version: 3.1.1
 Summary: Maintenance helpers for a Plex Media Server
 Author: Milkmansson
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: System :: Systems Administration
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: plexapi>=4.18
@@ -35,11 +35,11 @@ Dynamic: license-file
 # plextool
 
 > [!WARNING]
-> Still in development/testing... please raise an issue if you find one!
+> Still in development/testing... please raise an issue if one is found!
 
-Command line tools for Plex library maintenance, built on
-[python-plexapi](https://python-plexapi.readthedocs.io/). They talk to the
-server through its API. Nothing here touches the Plex database file, which is
+Command line tool for Plex library maintenance, built on
+[python-plexapi](https://python-plexapi.readthedocs.io/). It talks to the
+server through its API. No access is made to the Plex database file, which is
 too risky to edit by hand.
 
 ## What it is useful for
@@ -49,8 +49,8 @@ things Plex's web interface can't, and finding problems across a large library.
 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 you rebuild the database, delete
-  duplicate files and rescan, or reorganise files on disk, everything shows up as
+  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
@@ -60,7 +60,7 @@ Typical jobs:
   $ plextool recent --title "Some Show" --shift=-30d --commit
   ```
 - **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 you don't want.
+  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.
 - **Audit a library.** [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) reports unmatched items, missing files,
@@ -79,8 +79,8 @@ Typical jobs:
 - **Script Plex.** Reports can print JSON, and exports can go through a pipe, so the output
   feeds other tools.
 
-Everything that changes the server is a preview until you pass `--commit`. plextool uses Plex's API and
-never edits the Plex database file. It signs in through your browser with
+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)).
 
@@ -88,8 +88,8 @@ internet, or directly with no internet access ([`plextool server`](https://plext
 
 | 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 your account, and wipe the saved login and keys. |
-| [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on your account or network and choose the one to use. Covers working offline or directly against the server. |
+| [`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 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 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. |
@@ -101,8 +101,8 @@ internet, or directly with no internet access ([`plextool server`](https://plext
 | [`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 you pass
-`--commit`. Deleting files (`dupes --keep`) also asks you to type `DELETE`.
+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
 
@@ -110,9 +110,9 @@ 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 you don't want one
+$ 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 your Plex account and on your network
+$ 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
 ```
@@ -135,21 +135,21 @@ $ plextool subs fetch -t "Some Movie" --lang sv --choose --export --commit   # s
 **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 you pick the subtitle from the player's subtitle menu.
+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 you run it on must be able to read the media files. If it sees
+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 machine you are typing on, skip `server find` and `server use`:
+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).
 
@@ -163,19 +163,36 @@ $ 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 is tested on Python 3.12. It declares Python 3.9 or later, so pip will
-install it on older versions. If something doesn't work on one, please
-[open an issue](https://github.com/milkmansson/plextool/issues) with your Python
+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. You only need the ones for the file types
-you use.
+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
@@ -208,16 +225,16 @@ 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 you).
+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.
 
-If you would rather supply your own [Plex token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/),
-plextool looks for one in this order: `--token`, `--token-file FILE` (`-` for
+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 your shell history.
+token in the shell history.
 
 ## Development
 
@@ -228,5 +245,5 @@ $ pytest
 
 ## Disclaimer
 
-These tools only use the documented plexapi calls, but they do write to your
-server when you pass `--commit`. Check the dry run first. Use at your own risk.
+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.

{plextool-3.0.1 → plextool-3.1.1}/README.md

@@ -1,11 +1,11 @@
 # plextool
 
 > [!WARNING]
-> Still in development/testing... please raise an issue if you find one!
+> Still in development/testing... please raise an issue if one is found!
 
-Command line tools for Plex library maintenance, built on
-[python-plexapi](https://python-plexapi.readthedocs.io/). They talk to the
-server through its API. Nothing here touches the Plex database file, which is
+Command line tool for Plex library maintenance, built on
+[python-plexapi](https://python-plexapi.readthedocs.io/). It talks to the
+server through its API. No access is made to the Plex database file, which is
 too risky to edit by hand.
 
 ## What it is useful for
@@ -15,8 +15,8 @@ things Plex's web interface can't, and finding problems across a large library.
 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 you rebuild the database, delete
-  duplicate files and rescan, or reorganise files on disk, everything shows up as
+  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
@@ -26,7 +26,7 @@ Typical jobs:
   $ plextool recent --title "Some Show" --shift=-30d --commit
   ```
 - **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 you don't want.
+  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.
 - **Audit a library.** [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) reports unmatched items, missing files,
@@ -45,8 +45,8 @@ Typical jobs:
 - **Script Plex.** Reports can print JSON, and exports can go through a pipe, so the output
   feeds other tools.
 
-Everything that changes the server is a preview until you pass `--commit`. plextool uses Plex's API and
-never edits the Plex database file. It signs in through your browser with
+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)).
 
@@ -54,8 +54,8 @@ internet, or directly with no internet access ([`plextool server`](https://plext
 
 | 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 your account, and wipe the saved login and keys. |
-| [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on your account or network and choose the one to use. Covers working offline or directly against the server. |
+| [`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 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 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. |
@@ -67,8 +67,8 @@ internet, or directly with no internet access ([`plextool server`](https://plext
 | [`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 you pass
-`--commit`. Deleting files (`dupes --keep`) also asks you to type `DELETE`.
+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
 
@@ -76,9 +76,9 @@ 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 you don't want one
+$ 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 your Plex account and on your network
+$ 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
 ```
@@ -101,21 +101,21 @@ $ plextool subs fetch -t "Some Movie" --lang sv --choose --export --commit   # s
 **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 you pick the subtitle from the player's subtitle menu.
+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 you run it on must be able to read the media files. If it sees
+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 machine you are typing on, skip `server find` and `server use`:
+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).
 
@@ -129,19 +129,36 @@ $ 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 is tested on Python 3.12. It declares Python 3.9 or later, so pip will
-install it on older versions. If something doesn't work on one, please
-[open an issue](https://github.com/milkmansson/plextool/issues) with your Python
+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. You only need the ones for the file types
-you use.
+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
@@ -174,16 +191,16 @@ 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 you).
+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.
 
-If you would rather supply your own [Plex token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/),
-plextool looks for one in this order: `--token`, `--token-file FILE` (`-` for
+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 your shell history.
+token in the shell history.
 
 ## Development
 
@@ -194,5 +211,5 @@ $ pytest
 
 ## Disclaimer
 
-These tools only use the documented plexapi calls, but they do write to your
-server when you pass `--commit`. Check the dry run first. Use at your own risk.
+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.

{plextool-3.0.1 → plextool-3.1.1}/plextool/__init__.py

@@ -1,3 +1,3 @@
 """plextool: maintenance helpers for a Plex Media Server, built on python-plexapi."""
 
-__version__ = "3.0.1"
+__version__ = "3.1.1"

{plextool-3.0.1 → plextool-3.1.1}/plextool/audit.py

@@ -16,6 +16,8 @@ from .common import (
     paint,
     pick_sections,
     plural,
+    scan,
+    working,
 )
 
 LOW_RES = {"sd", "480", "576", "360", "240"}
@@ -82,12 +84,14 @@ def run_check(name: str, items: list, lang: str | None) -> list[dict]:
     """Apply one check to items; returns [{'item': description, 'reason': ...}]."""
     func, _, _, needs_full = CHECKS[name]
     found = []
-    for item in items:
-        if needs_full:
-            item.reload()
-        reason = func(item, lang)
-        if reason:
-            found.append({"item": describe(item), "reason": reason})
+    with working(f"checking {name}") as progress:
+        for number, item in enumerate(items, start=1):
+            progress.detail = f"{number} of {len(items)} items"
+            if needs_full:
+                item.reload()
+            reason = func(item, lang)
+            if reason:
+                found.append({"item": describe(item), "reason": reason})
     return found
 
 
@@ -124,7 +128,7 @@ def run(args: argparse.Namespace) -> int:
         for name in names:
             level = FILE_LEVEL[section.TYPE] if CHECKS[name][1] else section.TYPE
             if level not in cache:
-                cache[level] = section.search(libtype=level)
+                cache[level] = scan(section, libtype=level)
             report.setdefault(name, {})[section.title] = run_check(name, cache[level], args.lang)
 
     if args.json:

{plextool-3.0.1 → plextool-3.1.1}/plextool/cli.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import sys
+import time
 
 from . import (
     __version__,
@@ -20,7 +21,10 @@ from . import (
     subs,
     watched,
 )
-from .common import PlexToolError
+from .common import PlexToolError, enable_verbose, format_duration
+
+# Seconds a command must take before its total time is printed (always printed with --verbose).
+SHOW_TIME_AFTER = 5
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -31,6 +35,8 @@ def build_parser() -> argparse.ArgumentParser:
                "Anything that changes your server is a dry run unless you pass --commit.",
         formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("-v", "--verbose", dest="verbose_first", action="store_true",
+                        help="print each request sent to Plex, with its reply, on stderr (also accepted after the command)")
     subparsers = parser.add_subparsers(dest="command", metavar="command")
     for module in (auth, server, status, scan, recent, dupes, stale, audit, watched, resume, playlists, subs):
         module.add_parser(subparsers)
@@ -43,8 +49,16 @@ def main(argv: list[str] | None = None) -> int:
     if not args.command:
         parser.print_help()
         return 0
+    verbose = args.verbose_first or getattr(args, "verbose", False)
+    if verbose:
+        enable_verbose()
+    started = time.monotonic()
     try:
-        return args.run(args)
+        status = args.run(args)
+        elapsed = time.monotonic() - started
+        if verbose or elapsed >= SHOW_TIME_AFTER:
+            print(f"Finished in {format_duration(elapsed)}", file=sys.stderr)
+        return status
     except PlexToolError as e:
         print(f"error: {e}", file=sys.stderr)
         return 2