Command line

Everything the web interface manages can also be done from the terminal with the podvault command, which makes it easy to script.

podvault --help             # list all commands
podvault <command> --help   # options for one command

In Docker, run it inside the container:

docker exec podvault podvault --help
# or, with Compose:
docker compose exec podvault podvault --help

Most commands take a podcast_name. That’s the normalized name shown by podvault list (for example planet_money), not the display title.

Commands at a glance

Command	What it does
add	Add a feed URL and process it
process-feeds	Process all feeds from feeds.txt
list	List all podcasts in the database
status	Show download status
download	Download all episodes for a podcast
download-last	Download only the latest episode
episodes	List a podcast’s episodes with their id and status
rename	Set (or clear) an episode’s custom display name
verify	Check that downloaded episodes still exist on disk
config	Show or update the folder/filename naming templates
migrate-layout	Move downloaded episodes to the current naming template
schedule	Show or update a podcast’s auto-refresh schedule
opml-import	Import feeds from an OPML file and sync the new ones
opml-export	Export the original feed subscriptions as OPML
backup	Back up the database now, or list existing backups
serve	Start the web interface

Feeds

add

podvault add https://feeds.example.com/podcast.rss

Adds the feed to your feed list (feeds.txt, or wherever PODVAULT_FEEDS_FILE points) and processes it right away. Accepts RSS URLs and Apple Podcasts links.

process-feeds

podvault process-feeds
podvault process-feeds --file my-feeds.txt

Reads every URL in the feed list, converts Apple Podcasts links to RSS, extracts each episode’s metadata and stores it in the database. The feed list has one URL per line; lines starting with # are comments:

feeds.txt

# Technology
https://feeds.example.com/podcast.rss
https://podcasts.apple.com/us/podcast/example-podcast/id123456789

# News
https://another-podcast.com/feed.xml

The database is backed up automatically before feeds are synced (see backups).

list

podvault list

Shows every podcast in the database with download statistics.

status

podvault status                 # all podcasts
podvault status podcast_name    # one podcast

Shows download status.

Downloads

download

podvault download podcast_name

Downloads every episode of a podcast that isn’t downloaded yet, newest first. It shows how many episodes will be downloaded and asks for confirmation, then downloads them with a pause between each one (5 seconds by default, PODVAULT_DEFAULT_DELAY_SECONDS). Tags, cover art and the original RSS entry are written for each episode.

Episodes marked missing (see verify) are downloaded again.

download-last

podvault download-last podcast_name

Downloads only the newest episode that isn’t downloaded yet.

verify

podvault verify                  # every podcast
podvault verify podcast_name     # one podcast

Files can disappear without the database knowing: moved, deleted, or on an external drive that’s unplugged. verify checks every episode marked as downloaded and, if its file is gone, marks it missing. The next download or download-last picks it up again.

Episodes

episodes

podvault episodes podcast_name

Lists a podcast’s episodes with their id, current name and status. Use the id with rename.

rename

podvault rename podcast_name <episode_id> "New Episode Title"
podvault rename podcast_name <episode_id> ""     # clear the custom name

Gives an episode a custom display name. It updates the title tag and, if the episode is already downloaded, renames its folder and files to match. The custom name is kept separately from the feed’s title, so re-processing feeds never overwrites it. If the episode isn’t downloaded yet, the name is used when it is.

Naming and layout

config

# Show the current templates
podvault config

# Change one or both (only the ones you pass are updated)
podvault config --folder-template "{podcast_name}/{year}/{episode_label} - {episode_title}"
podvault config --filename-template "{episode_number} - {episode_title}"

Shows or updates the folder and filename templates. Templates are validated before saving. See naming templates for the variables. A new template only affects future downloads.

migrate-layout

podvault migrate-layout           # dry run: lists what would move, changes nothing
podvault migrate-layout --apply   # moves the files and updates the database

Moves files you’ve already downloaded into the current naming template. You only need it after changing a template. It’s a dry run unless you pass --apply. Check the dry-run list first: this moves real files on disk, which is why it’s only available from the CLI. (The web interface’s Storage page shows the same dry-run list.)

Schedules

schedule

# Show a podcast's schedule
podvault schedule podcast_name

# Check the feed every 12 hours and download new episodes automatically
podvault schedule podcast_name --interval-hours 12 --auto-download

# Check on a schedule, but leave downloading to you
podvault schedule podcast_name --interval-hours 24 --no-auto-download

# Turn it off
podvault schedule podcast_name --disable

Schedules only run while the web server is running (podvault serve, or the Docker container). A background thread wakes up every PODVAULT_SCHEDULER_POLL_INTERVAL_SECONDS (300 by default) and re-syncs any podcast whose interval has passed. They don’t run from plain CLI commands, and serve --reload skips them.

OPML

opml-import

podvault opml-import subscriptions.opml

Adds every feed from an OPML file exported by another podcast app and syncs the new ones. Feeds you already have are skipped, so importing the same file twice is harmless. See OPML.

opml-export

podvault opml-export -o podvault_subscriptions.opml   # to a file
podvault opml-export                                  # print to the terminal

Exports your original feed subscriptions as OPML.

Backups

backup

podvault backup          # back up the database now, then list backups
podvault backup --list   # only list existing backups

Forces a database backup right away, ignoring the usual once-a-day limit. See Archive safety.

Web server

serve

podvault serve                                   # http://127.0.0.1:8000
podvault serve --host 0.0.0.0 --port 8000        # reachable from your network

Starts the web interface and the auto-refresh scheduler. When binding to anything other than a local address, set PODVAULT_USERNAME and PODVAULT_PASSWORD; serve warns you if there’s no login, and names the missing variable if only one is set. The --reload flag is for development and doesn’t start the scheduler.

Playback, job control (pause, resume, skip, cancel), integrity checks and export are only in the web interface.