Read-only command line tools for inspecting the local Apple TV app library on macOS.
The first practical goal is simple:
- list downloaded Apple TV media files
- show how much disk space they use
- optionally ask TV.app for library metadata through its scripting interface
This project does not parse or write Apple TV's private .tvdb files. Those
files are private Apple data formats and are not SQLite databases.
uv tool install --from . apple-tv-cliFor development:
uv run atv downloads
uv run atv report --jsonatv downloadsScans the configured TV media folder and reports downloaded video files and their exact filesystem sizes.
atv library [--limit N] [--timeout SECS] [--verbose]Asks TV.app for library track metadata using macOS scripting. On first use macOS
may prompt for Automation permission. Use --verbose to see per-step timing,
which is useful if the query is unexpectedly slow.
On macOS 26/Tahoe, TV.app still publishes a scripting dictionary, but several
users report that object access through AppleScript is currently broken. When
that happens, atv library exits non-zero and atv report includes a
structured library.ok: false result while still reporting downloaded file disk
usage.
atv reportShows a summary: total library items by kind, total size, which files are
downloaded locally, and how many remain cloud-only. Use --strict-library if
scripts should fail when the TV.app metadata backend is unavailable.
atv doctorShows the paths and capabilities the tool can currently see.
The media folder is read from:
~/Library/Preferences/com.apple.TV.plist
If that preference is missing, the CLI falls back to:
~/Movies/TV/Media.localized
MIT — see LICENSE.
- Apple TV app library on Mac: https://support.apple.com/guide/tvapp-mac/manage-your-library-atvbe9ddc3f/mac
- macOS scripting dictionaries: https://support.apple.com/guide/script-editor/view-an-apps-scripting-dictionary-scpedt1126/mac
- macOS 26 TV.app AppleScript reports: https://discussions.apple.com/thread/256150063