Podcats

A minimalist CLI podcast client. Episodes download to a flat file structure suitable for syncing to cheap MP3 players.

Install

uv tool install .

This installs podcats into an isolated environment and makes it available on your PATH. To update after changes:

uv tool install . --force

For development, use uv sync instead to set up the project with dev dependencies.

Getting started

All commands require --lib (or -l) to specify the library directory. This directory holds the SQLite database and all downloaded episodes.

Before using podcats, initialize a library:

podcats --lib ~/podcasts init

This creates the directory and database. Other commands will refuse to run if the library hasn't been initialized, so there's no risk of accidentally creating a database in the wrong place.

Then subscribe to a feed:

podcats --lib ~/podcasts sub https://example.com/feed.xml

By default, only the 10 most recent episodes are queued for download. To grab everything, use --all, or set a specific number with --limit:

podcats --lib ~/podcasts sub --all https://example.com/feed.xml
podcats --lib ~/podcasts sub --limit 5 https://example.com/feed.xml

Then sync to fetch new episodes and download them:

podcats --lib ~/podcasts sync

Sync refreshes feeds at most once every 4 hours to avoid hammering providers.

Commands

podcats --lib ~/podcasts list

List all subscriptions alphabetically with episode counts.

podcats --lib ~/podcasts episodes <name>

List episodes for a podcast. Shows download status, date, and title. Podcast name matching is case-insensitive.

• [x] downloaded
• [ ] pending download
• [-] skipped

podcats --lib ~/podcasts unsub <name>

Unsubscribe from a podcast and remove its episodes from the database. Downloaded files are left on disk. Name matching is case-insensitive.

Library structure

~/podcasts/
  podcats.db
  My Great Podcast/
    2024-01-15 - Episode Title.mp3
    2024-01-08 - Another Episode.mp3
  Another Show/
    2024-02-01 - First Episode.mp3

Filenames are sanitized for FAT32 compatibility. Podcats uses its SQLite database to track download status, not the files on disk. If you delete episodes you no longer want, they won't be redownloaded.

Development

./check

Runs ruff lint, ruff format check, and pytest.