podboat - Man Page

a podcast download manager for text terminals


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


podboat is a podcast manager for text terminals. It is a helper program to newsboat which queues podcast downloads into a file. These queued downloads can then be download with podboat.


-h,  --help

Display help

-C configfile, --config-file=configfile

Use an alternative configuration file

-q queuefile, --queue-file=queuefile

Use an alternative queue file

-a,  --autodownload

Start automatic download of all queued files on startup

-l loglevel, --log-level=loglevel

Generate a logfile with a certain loglevel. Valid loglevels are 1 to 6. An actual logfile will only be written when you provide a logfile name.

-d logfile, --log-file=logfile

Use this logfile as output when logging debug messages. Please note that this only works when providing a loglevel.

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 contains support for downloading and saving podcasts. This support differs a bit from other podcast aggregators or "podcatchers" in how it is done.

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. What the user then can do is to add the podcast download URL to a download queue. Alternatively, newsboat can be configured to automatically do that. This queue is stored in the queue file next to the cache.db file.

The user can then use the download manager podboat to download these files to a directory on the local filesystem. Podboat comes with the newsboat package, and features a look and feel very close to the one of newsboat. It also shares the same configuration file.

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 "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.

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 "Format Strings" section of Newsboat manual for details on available formats. 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 "Format Strings" section of 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 respective section in the documentation for more information on format strings. (example: podlist-format "%i %u %-20S %F")


By default, Newsboat stores all the files in a traditional Unix fashion, i.e. in the "dotdir" located at ~/.newsboat. However, it also supports a modern way, XDG Base Directory Specification, which splits the files between the following locations:

If these directories exist or the environment variables $XDG_CONFIG_HOME and $XDG_DATA_HOME are set, newsboat will use these directories, otherwise it will default to ~/.newsboat as its configuration directory.

If you’re currently using ~/.newsboat/ but wish to migrate to XDG directories, you should move the files as follows:

config,  urls

to $HOME/.config/newsboat/

cache.db,  history.search,  history.cmdline,  queue

to $HOME/.local/share/newsboat/









Tells Newsboat what browser to use if there is no browser setting in the config file. If this variable doesn’t exist, a default of lynx(1) will be used.


Tells Newsboat to use the specified certificate file to verify the peer. The file may contain multiple certificates. The certificate(s) must be in PEM format.

This option is useful if your libcurl is built without useful certificate information, and you can’t rebuild the library yourself.


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) will be used.


Tells Newsboat what pager to use if the pager setting in the config file is explicitly set to an empty string.


Tells Newsboat to use the specified directory for storing temporary files. If this variable doesn’t exist, a default of /tmp will be used.


Tells Newsboat what editor to use when editing the urls file via the edit-urls operation. If this variable doesn’t exist, the EDITOR environment variable will be used.


Tells Newsboat which base directory to use for the configuration files. See also the section on files for more information.


Tells Newsboat which base directory to use for the data files. See also the section on files for more information.

See Also



Alexander Batischev

Referenced By