name: podpull description: Use when the user wants to download a podcast episode's audio file (mp3/m4a) to disk — from an Apple Podcasts show or episode link, a raw RSS feed, or a 小宇宙/xiaoyuzhou episode link. Covers searching for a show, listing episodes, and downloading one or many. Keywords: download podcast, save episode audio, Apple Podcasts, RSS, xiaoyuzhou, 小宇宙, mp3, m4a, podpull, 下载播客.

podpull — download podcast episode audio

Use the installed podpull command-line tool to download podcast audio. Repo: https://github.com/xiaoleiy/podpull

If it isn't installed: brew install xiaoleiy/tap/podpull (macOS/Linux) or pipx install git+https://github.com/xiaoleiy/podpull.

How it works (so you pick the right command)

Apple Podcasts holds no audio — it points at each show's RSS feed, where every episode has a direct <enclosure> URL. podpull resolves Apple show URLs/IDs, raw RSS feeds, and xiaoyuzhou links to that audio and downloads it.

Commands

podpull search "<keywords>"                  # find shows -> Apple ID, #episodes, name
podpull info  <src>                          # show metadata (title, author, feed, latest)
podpull list  <src> [--match RE] [--all]     # list episodes; index 0 = newest
podpull get   <src> --match RE | --latest N | --index 0,2[,..]   # download (alias: `pull`)
podpull get   <episode-url>                  # download a pasted Apple ?i= or xiaoyuzhou link
podpull get   <src> ... -q / --quiet         # suppress spinner/progress bar
podpull --json <cmd> …                       # one JSON document on stdout (flag before command)
podpull serve [--host] [--port]              # local UI: search / trending / browser download

Hosted web UI (same idea, no install): https://podpull.xiaolei.work/app

<src> = Apple show URL · bare Apple ID · RSS feed URL · Apple episode ?i= URL · xiaoyuzhou episode URL.

Workflow

Resolve the show: if you only have a name, podpull search "<name>"; then podpull list <id> to see episodes.
Download with a selector — --match (title regex), --latest N, or --index 0,2.
Report the saved path. The file path is printed to stdout; progress/UI go to stderr, so capture stdout when scripting.

Important for agents (non-interactive)

Always pass a selector and --no-input. Running podpull get <show> with no selector opens an interactive keyboard picker — which can't be driven non-interactively and will instead error with a hint. Use e.g. podpull get 1532755821 --latest 1 --no-input.
Add -q/--quiet to suppress the spinner and live progress bar on stderr — recommended for agent transcripts, since neither renders meaningfully outside a live terminal. Saved file paths still print to stdout either way.
Prefer podpull --json … when you need structured data (search / info / list / get). The flag goes before the command. On success stdout is one JSON document; on failure check the exit code (human error on stderr, no JSON).
Downloads default to ~/Downloads/Podcasts; pass --out DIR to change.
Selecting multiple episodes creates a per-show sub-folder. Filenames are normalized to be cloud-storage-safe (emoji/illegal characters removed; CJK kept).
Optional: if PODCASTINDEX_API_KEY/PODCASTINDEX_API_SECRET are set, search also queries Podcast Index and feed resolution gains a fallback; ximalaya.com/album/ links work as a source.

Examples

podpull search "睡前故事"
podpull --json list 1532755821 --limit 5
podpull get 1532755821 --latest 1 --no-input --quiet
podpull --json get 1532755821 --latest 1 --no-input
podpull get 1532755821 --match "牛頭人" --no-input --out ~/Audio
podpull get "https://www.xiaoyuzhoufm.com/episode/<id>" --no-input

podpull — download podcast episode audio

Use the installed podpull command-line tool to download podcast audio. Repo: https://github.com/xiaoleiy/podpull

If it isn't installed: brew install xiaoleiy/tap/podpull (macOS/Linux) or pipx install git+https://github.com/xiaoleiy/podpull.

How it works (so you pick the right command)

Commands

podpull search "<keywords>" # find shows -> Apple ID, #episodes, name podpull info <src> # show metadata (title, author, feed, latest) podpull list <src> [--match RE] [--all] # list episodes; index 0 = newest podpull get <src> --match RE | --latest N | --index 0,2[,..] # download (alias: `pull`) podpull get <episode-url> # download a pasted Apple ?i= or xiaoyuzhou link podpull get <src> ... -q / --quiet # suppress spinner/progress bar podpull --json <cmd> … # one JSON document on stdout (flag before command) podpull serve [--host] [--port] # local UI: search / trending / browser download

<src> = Apple show URL · bare Apple ID · RSS feed URL · Apple episode ?i= URL · xiaoyuzhou episode URL.

Workflow

Resolve the show: if you only have a name, podpull search "<name>"; then podpull list <id> to see episodes.

Download with a selector — --match (title regex), --latest N, or --index 0,2.

Report the saved path. The file path is printed to stdout; progress/UI go to stderr, so capture stdout when scripting.

Important for agents (non-interactive)

Always pass a selector and --no-input. Running podpull get <show> with no selector opens an interactive keyboard picker — which can't be driven non-interactively and will instead error with a hint. Use e.g. podpull get 1532755821 --latest 1 --no-input.

Add -q/--quiet to suppress the spinner and live progress bar on stderr — recommended for agent transcripts, since neither renders meaningfully outside a live terminal. Saved file paths still print to stdout either way.

Prefer podpull --json … when you need structured data (search / info / list / get). The flag goes before the command. On success stdout is one JSON document; on failure check the exit code (human error on stderr, no JSON).

Downloads default to ~/Downloads/Podcasts; pass --out DIR to change.

Selecting multiple episodes creates a per-show sub-folder. Filenames are normalized to be cloud-storage-safe (emoji/illegal characters removed; CJK kept).

Optional: if PODCASTINDEX_API_KEY/PODCASTINDEX_API_SECRET are set, search also queries Podcast Index and feed resolution gains a fallback; ximalaya.com/album/ links work as a source.

Examples

podpull search "睡前故事" podpull --json list 1532755821 --limit 5 podpull get 1532755821 --latest 1 --no-input --quiet podpull --json get 1532755821 --latest 1 --no-input podpull get 1532755821 --match "牛頭人" --no-input --out ~/Audio podpull get "https://www.xiaoyuzhoufm.com/episode/<id>" --no-input