PODBOAT(1)

📦
version 2.45 · 14 versions
, in fedora 43, fedora 44

💖 PODBOAT(1) — podboat 💖

okay bestie, gather round, because we're talking about podboat, aka a podcast download manager for text terminals 🎧✨. Yes she's a terminal girlie. Yes she's iconic. Let's get into it.

✨ NAME ✨

podboat — a podcast download manager for text terminals 🎀

🌸 SYNOPSIS 🌸

podboat [-C configfile] [-q queuefile] [-a] [-h]

🦋 DESCRIPTION 🦋

So podboat is a podcast manager for text terminals, no cap. She's a helper program to Newsboat — her whole job is queueing podcast downloads into a file. Then, once those downloads are sitting pretty in the queue, podboat is what actually downloads them. Teamwork, literally 💅

💅 OPTIONS 💅

  • -h, --help — Display help. The "wait what do I do" button 🫶
  • -C configfile, --config-file=configfile — Use an alternative configuration file. Different config, different vibe 💜
  • -q queuefile, --queue-file=queuefile — Use an alternative queue file. Point her at a different queue 🍓
  • --lock-file=lockfile — Use an alternative lock file 🔒
  • -a, --autodownload — Start automatic download of all queued files on startup. She just goes. Main character energy 🔥
  • -l loglevel, --log-level=loglevel — Generate a logfile with a certain loglevel. Valid values are 1 to 6, which are, respectively: user error, critical, error, warning, info, and debug. The filename can be specified using the --log-file option. If you don't specify one, a filename gets generated of the form podboat_<date-time>.log ⭐
  • -d logfile, --log-file=logfile — Use this logfile as output when logging debug messages. Heads up though: this only works when providing a loglevel. No loglevel, no logfile, that's the rule 🙈

🌈 PODCAST SUPPORT 🌈

A podcast is a media file distributed over the internet using syndication feeds such as RSS, for later playback on portable players or computers. Newsboat supports downloading, saving and streaming podcasts — but an external media player is needed for playback, just so you know. And the way this support works differs a bit from other podcast aggregators, or "podcatchers" as the girlies say 👑

Podcast content is transported in RSS feeds via special tags called "enclosures". Newsboat recognizes these enclosures and stores the relevant information for every podcast item it finds in an RSS feed. Since version 2.0, it also recognizes and handles the Yahoo Media RSS extensions. Slay 💖

Remote APIs don't always list those "enclosures", so podcasts might be missing from Newsboat. Such APIs are marked in the relevant section of our docs. If a note is missing but you still don't see enclosures in Newsboat, please file an issue and we'll get to the bottom of it! 🕵️‍♀️

🎀 MANAGING AUDIO FILES WITH PODBOAT 🎀

What you can do is add the podcast download URL to a download queue. Alternatively, Newsboat can be configured to automatically do that for you. This queue is stored in the queue file next to the cache.db file. Bestie behavior honestly 🫶

Then you use the download manager podboat to download these files to a directory on the local filesystem. podboat comes with the Newsboat package, and her look and feel is very close to the one of Newsboat — same energy, same configuration file, it's giving sisters 💅

Podcasts that have been downloaded but haven't been played yet remain in the queue but are marked as downloaded. You can remove them by purging them from the queue with the Shift + P key. After you've played a file and close Podboat, it will be removed from the queue. The downloaded file remains on the filesystem unless "delete-played-files" is enabled. Yes, that's a whole thing, keep reading 📖

A common "use case" is to configure Newsboat to automatically enqueue newly found podcast download URLs. Then, the user reloads the podcast RSS feeds in Newsboat, and after that, uses Podboat to view the current queue, and either selectively download certain files or automatically download them all together by pressing A within Podboat. Pick your fighter ⚔️

🌸 CONFIGURATION COMMANDS 🌸

delete-played-files (parameters: [yes/no]; default value: no)

If set to yes, Podboat will delete files when their corresponding queue entry is removed (this includes "finished" and "deleted" entries as well). Example: delete-played-files yes

download-path (parameters: <path>; default value: ~/)

Specifies the directory where Podboat shall download the files to. Optionally, placeholders can be used to place downloads in a directory structure. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. Heads up: this setting is applied at enqueueing time — changing it won't affect download paths of the podcasts that were already added to the queue. Example: download-path "~/Downloads/%h/%n"

download-filename-format (parameters: <string>; default value: "%?u?%u&%Y-%b-%d-%H%M%S.unknown?")

Specifies how Podboat would name the files it downloads (see also download-path). See the FORMAT STRINGS section of the Newsboat manual for details on available formats. Example: download-filename-format "%F-%t.%e"

max-downloads (parameters: <number>; default value: 1)

Specifies the maximum number of parallel downloads when automatic download is enabled. Example: max-downloads 3

player (parameters: <player command>; default value: "")

Specifies the player that shall be used for playback of downloaded files. Example: player "mp3blaster"

podlist-format (parameters: <format>; default value: "%4i [%6dMB/%6tMB] [%5p %%] [%12K] %-20S %u → %F")

This variable defines the format of entries in Podboat's download list. See the FORMAT STRINGS section in the documentation for more information on format strings. Example: podlist-format "%i %u %-20S %F"

⭐ FORMAT STRINGS ⭐

Newsboat contains a powerful format string system to make it possible for the user to configure the format of various aspects of the application, such as the format of entries in the feed list or in the article list. Powerful and pretty, we love that for her 💖

Format strings are similar to those that are found in the printf function in the C programming language. A format sequence begins with the % character, followed by optional alignment indication: positive numbers indicate that the text that is inserted for the sequence shall be padded on the left to a total width that is specified by the number, while negative number specify padding on the right. Followed by the padding indication comes the actual sequence identifier, which is usually a single letter. %=[width][identifier] centers the sequence, where if w=0 the whole width of the window is used. ✨

In addition, Newsboat provides other, more powerful sequences, such as %>[char], which indicates that the text right to the sequence will be aligned right on the screen, and characters between the text on the left and the text on the right will be filled by [char]. Another powerful format is the conditional sequence, %?[char]?[format 1]&[format 2]?: if the text of the sequence identifier [char] contains any non-whitespace characters, then [format 1] will be evaluated and inserted, otherwise [format 2] will be evaluated and inserted. The & and [format 2] are optional, i.e. if the identifier's text is empty, then an empty string will be inserted. Chef's kiss, honestly 👩‍🍳💋

The following tables show what sequence identifiers are available for which format:

Table 1. Available Identifiers for feedlist-format

  • d — Feed description
  • i — Feed index
  • l — Feed link
  • L — Feed RSS URL
  • n — "unread" flag field
  • S — download status
  • t — Feed title
  • T — First tag of a feed in the URLs file
  • u — "unread/total" field
  • U — "unread" field
  • c — "total" field

While a reload-all operation is running, the download status indicates the download status of a feed, which can be "to be downloaded" (indicated by "_"), "currently downloading" (indicated by "."), successfully downloaded (indicated by " ") and "download error" (indicated by "x"). 🦋

ok bestie, these are the actual cheat-sheets for what you can slot into each format string ✨ every single identifier, every single meaning, no skips, no cap 💅

🎀 Table 2. Available Identifiers for articlelist-format 🎀

here's what you can put in your article list format, one by one:

  • a — the article's author 👑
  • D — the publication date. you can tweak this even more with datetime-format, iykyk
  • f — two characters, together, as a lil duo: 1) "N" if the article is unread, "D" if the article is deleted, and a space otherwise; 2) "!" if the article has flags, and a space otherwise. two slots, one identifier, she contains multitudes 💀
  • n — the "unread" field
  • d — the "deleted" field
  • F — the article flags
  • i — the article index
  • t — the article title
  • T — if the article list is showing articles from different feeds, then this identifier holds the title of the feed that the article belongs to 🦋
  • L — the article length
  • e — the article enclosure URL

🌸 Table 3. Available Identifiers for selecttag-format 🌸

the tag-picker's own lil set of identifiers, periodt:

  • i — the line's index in the list
  • T — the tag that this line corresponds to
  • f — number of unread feeds under this tag
  • n — number of unread articles in feeds tagged with this tag
  • u — number of feeds tagged with this tag

🦋 Table 4. Available Identifiers for notify-format 🦋

and for your notifications, bestie, the whole menu:

  • n — number of unread articles
  • f — number of unread feeds
  • d — number of new unread articles (i.e. that were added through the last reload) 🔥
  • D — number of new unread feeds (i.e. that were added through the last reload)

💖 Table 5. Available Identifiers for podlist-format 💖

okay so when you're building out your podlist-format, these are the little letter codes you get to play with — go feral bestie 💅

  • i — the download index ✨
  • d — currently downloaded size in megabytes, and it shows one digit of precision
  • t — total download size in megabytes, also one digit of precision
  • p — downloaded percentage, one digit of precision
  • k — download speed, two digits of precision, always in KB/s. And heads up: it does not include the "KB/s" text, so if you want that you add it yourself, iykyk
  • K — download speed, two digits of precision, but human readable — it automatically switches between KB/s, MB/s and GB/s 🦋
  • S — status of the download. It shows one of these: "queued", "downloading", "ready", "canceled", "deleted", "missing", "played", "finished" or "failed"
  • u — the URL of the download
  • F — absolute filename of the download from the root directory (like ~/downloads/podcast.mp3 → /home/name/downloads/podcast.mp3)
  • b — basename of the download (so /home/name/downloads/podcast.mp3 → podcast.mp3)

🎀 Table 6. Available Identifiers for download-path and download-filename-format 🎀

these ones are for naming where your files actually land on disk, and they are so useful 🌸

  • u — the filename part of the download URL. May be empty. May include a query string (https://en.wikipedia.org/wiki/Query_string)
  • n — name of the podcast feed
  • N — name of the podcast feed, except this one keeps the original feed's name, even when you selected it through a query feed 👑
  • h — name of the podcast feed's hostname
  • t — title of the podcast episode
  • e — extension of the podcast episode
  • F — publication date of the podcast episode, formatted as yyyy-mm-dd
  • m — month when the podcast episode was published
  • b — abbreviated month name when the podcast episode was published
  • d — day when the podcast episode was published
  • H — hour when the podcast episode was published
  • M — minute when the podcast episode was published
  • S — second when the podcast episode was published
  • y — year when the podcast episode was published, formatted as yy
  • Y — year when the podcast episode was published, formatted as yyyy

🌈 Examples 🌈

fr fr, here's what it actually looks like in the wild:

feedlist-format     "%4i %n %11u %t"
articlelist-format  "%4i %f %D   %?T?|%-17T|  ?%t"
notify-format       "%d new articles (%n unread articles, %f unread feeds)"
podlist-format      "%4i [%-5p %%] %-12S %F"
bestie, copy these exactly — every space and every % is doing something, no cap 💜

📁 FILES 📁

Okay bestie, this is the part where we talk about where your stuff lives. By default, Newsboat keeps all its files the old-school traditional Unix way — a "dotdir" chilling at ~/.newsboat. Very vintage, very demure. But it also supports the modern way, the XDG Base Directory Specification (https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html), which splits your files between these two locations:

  1. $XDG_CONFIG_HOME/newsboat/ (and XDG_CONFIG_HOME defaults to ~/.config)
  2. $XDG_DATA_HOME/newsboat/ (and XDG_DATA_HOME defaults to ~/.local/share)

So here's the vibe check: if the newsboat directory exists under XDG_CONFIG_HOME, then Newsboat goes full XDG mode (and it'll create the data directory if it needs to). Otherwise? Newsboat just defaults back to ~/.newsboat. That's it, that's the rule. ✨

If you're currently living that ~/.newsboat/ life but you wanna glow up and migrate to XDG directories, move your files like this:

  • config, urls — move these to $XDG_CONFIG_HOME/newsboat/
  • cache.db, history.search, history.cmdline, queue — move these to $XDG_DATA_HOME/newsboat/

Newsboat and Podboat also create "lock files", and no, they're not trying to be possessive 💅. These prevent you from starting two instances of the same program at once, which would corrupt your data. Rude of you, honestly. Newsboat and Podboat delete these files when you quit, so you do not need to copy them anywhere — just be aware of them in case you write scripts that mess with cache.db or queue. By default, lock files live here:

  • Newsboat
    • dotdir: ~/.newsboat/cache.db.lock
    • XDG: $XDG_DATA_HOME/newsboat/cache.db.lock
  • Podboat
    • dotdir: ~/.newsboat/pb-lock.pid
    • XDG: $XDG_DATA_HOME/newsboat/.lock

Newsboat places the lock file right next to the cache file, so if you set the cache-file setting or pass the --cache-file command-line argument, the path to the lock file changes too. Iconic, consistent, we love that for us. Podboat's lock can be placed somewhere else entirely using the --lock-file command-line argument.

dotfiles:

  • ~/.newsboat/config
  • ~/.newsboat/queue

XDG:

  • $XDG_CONFIG_HOME/newsboat/config
  • $XDG_DATA_HOME/newsboat/queue
Note: if the XDG_CONFIG_HOME environment variable isn't set, Podboat behaves as if it was set to ~/.config. Similarly, XDG_DATA_HOME defaults to ~/.local/share. 🫶

🌍 ENVIRONMENT 🌍

These are the environment variables, aka the vibes your shell hands over before Podboat even wakes up:

  • BROWSER — Tells Newsboat what browser to use if there's no browser setting in the config file. If this variable doesn't exist, a default of lynx(1) gets used. Old reliable, fr fr.
  • CURL_CA_BUNDLE — Tells Newsboat to use the specified certificate file to verify the peer. The file may contain multiple certificates, and the certificate(s) must be in PEM format. This one is useful if your libcurl is built without useful certificate information and you can't rebuild the library yourself. No cap, this has saved people.
  • EDITOR — Tells Newsboat what fallback editor to use when editing the urls file via the edit-urls operation and no VISUAL environment variable is set. If this variable doesn't exist either, a default of vi(1) gets used.
  • NO_PROXY — Tells Newsboat to ignore the proxy setting for certain sites. This variable contains a comma-separated list of hostnames, domain names, and IP addresses. Domain names match subdomains, i.e. "example.com" also matches "foo.example.com". Domain names that start with a dot only match subdomains, e.g. ".example.com" matches "bar.example.com" but not "example.com" itself. IPv6 addresses are written without square brackets, and are matched as strings — thus "::1" doesn't match "::0:1" even though this is the same address. Sneaky little detail, bestie, write it down. 📝
  • PAGER — Tells Newsboat what pager to use if the pager setting in the config file is explicitly set to an empty string.
  • TMPDIR — Tells Newsboat to use the specified directory for storing temporary files. If this variable doesn't exist, a default of /tmp gets used.
  • **VISUAL``** — Tells Newsboat what editor to use when editing the urlsfile via theedit-urlsoperation. If this variable doesn't exist, theEDITOR` environment variable gets used instead. It's giving backup-bestie energy.
  • XDG_CONFIG_HOME — Tells Newsboat which base directory to use for the configuration files. See also the section on files for more information. 👀
  • XDG_DATA_HOME — Tells Newsboat which base directory to use for the data files. See also the section on files for more information. 👀

👀 SEE ALSO 👀

👑 AUTHOR 👑

Alexander Batischev

And that's the whole page, bestie!! 🎀 This was the PODBOAT(1) manual page, dated 2026-10-05. Go forth, read your queues, manage those downloads, and remember: lock files are not your enemy, they're just protecting you from yourself. 💖✨🦋

📦 where this page comes from