8 Sep 2025 - My newsboat config has changed significantly since I wrote this, so I updated the config file and did some other miscellaneous cleanup
The Internet is a vast place, with more content created every minute than I could hope to keep up with in a lifetime, so it's helpful to try and wrangle some of that info into a form that's easily consumable so I don't have to waste time hunting around for it. Enter: RSS Feeds.1. RSS feeds are basically XML files that a website operator can update to let subsribers know when a site was updated and what pages got the updates. It's handy because instead of clicking a mountain of bookmarks every time you open a web browser, you can just look at your RSS reader to see which sites have advertised updates, open the one that looks interesting that day, and you're done2.
There are lots of RSS readers out there, but the one I'm going to focus on today is newsboat. I use Newsboat because I can leave it running on a computer and then SSH back into it wherever I am3. Newsboat is extremely configurable, but I only really use a bare minimum of a configuration. My ~/.newsboat/config:
include /usr/local/share/doc/newsboat/contrib/colorschemes/inkpot
refresh-on-startup no
auto-reload yes
reload-time 120
reload-threads 100
browser links
max-downloads 4
keep-articles-days 14
macro v set browser "mpv --autofit-larger=25%x25%"; open-in-browser; set browser links
macro a set browser mpv
macro i set browser feh
macro g set browser "links -g"; open-in-browser; set browser links
macro f set browser "firefox --private-window"; open-in-browser; set browser links
macro z set browser links
# podboat config
player "mpv"
delete-played-files yes
download-path ~/Downloads/podboat
download-filename-format "%N %t"
podlist-format "%4i [%6dMB/%6tMB] [%5p %%] [%12K] %-20S → %b"
podcast-auto-enqueue yes
Newsboat and podboat share a configuration file, which makes things tidy, if not a little confusing. Most of the options are straightforward.
include /usr/local/share/doc/newsboat/contrib/colorschemes/inkpot Use the Inkpot colorscheme. The location of your colorschemes may vary. You could also create your own, but I didn't do that
refresh-on-startup no Don't refresh feeds when we start up newsboat
auto-reload yes Tells newsboat to automatically check for updated feeds
reload-time 120 Check for updates every 120 minutes
reload-threads 50 Check up to 50 feeds at once (this is helpful if you check a lot of feeds, but some of them are slow to respond)
browser links Use links to open links. There are other more capable browsers I could use, sure, but links works well enough for me and I can usually find the part of the page I'm interested in pretty quickly4
max-downloads 4 Download up to four files at once
keep-articles-days 14 Delete any articles older than 14 days. If I haven't gotten to the article in 14 days I probably won't get to it. Having an 'unread' counter that grows forever gives me anxiety, so I try to keep that to a minimum. Also, it's important to note that this only seems to apply if I shut newsboat down and then reopen it. If you keep it open forever, then the counter just increments indefinitely
I set up a bunch of macros for changing the browser around for a few different scenarios. The default key for executing a macro is the comma key and then the macro name. Like everything else, this is configurable
macro v set browser "mpv --autofit-larger=25%x25%"; open-in-browser; set browser links Runs a macro that sets my browser to the mpv player, with arguments to start out at 25% size, then open the link in the browser, then set the browser back to links when it's done. This is useful if I want to open up, say, a YouTube video, but I don't want to use a browser, since mpv can open up YouTube links and play the videos without getting a browser involved.
macro a set browser mpv This just sets the browser to mpv. I use this if there's a podcast or something that's super short and I don't want to bother enqueueing it in podboat, I'll just play it directly from the feed list. The main drawback of this is that I can't browse anything else in the queue until the file is over5
macro i set browser feh set the 'browser' to the feh image viewer. Useful if I just want to open a picture contained in a news item, but not the whole website.
macro g set browser "links -g"; open-in-browser; set browser links Sets my browser to Links, but in grapics mode. Just in case I want to see the page and the images at the same time.
macro f set browser "firefox --private-window"; open-in-browser; set browser links Opens the link in a private Firefox window
macro z set browser links Sets the browser back to Links after I changed it via one of the other macros
#Podboat Config
player "mpv" Tells podboat to use mpv to play downloaded media using mpv.
delete-played-files yes deletes podcast files after I listen to them
download-path ~/Downloads/podboat Save files in my home directory under Downloads/podboat
download-filename-format "%N %t" When you tell podboat you want to download a file, this tells it that you want to name the file with the name of the podcast and then the name of the episode. The default is just the URL of the podcast file, which isn't very useful, especially since a lot of podcasts use syndicators that give the URLs and downloaded files random names.
podlist-format "%4i [%6dMB/%6tMB] [%5p %%] [%12K] %-20S → %b" This tells podboat to generate a nice little status bar and then once the file is downloaded, show the name of the file you downloaded (see above entry). It's basically the default string with one character changed.
podcast-auto-enqueue yes every time newsboat finds a podcast in an enclosure tag, automatically enqueues it for later
Once you have some options configured, it's time to add some feeds to newsboat. You do this by editing a file ~/.newsboat/urls. This file is very straightforward. At minimum you need one url on each line pointing to an RSS feed you want to follow6. Finding RSS feeds can be tricky. Some sites will link to theirs right on the home page, some hide it in their View → Source, some hide it even better than that (there are even some sites that don't provide one at all, which is annoying). Once you have a list of feeds you want to check out, start newsboat, and you'll see a screen similar to the artist's rendering
Newsboat 2.27.0 - Your feeds (8 unread, 20 total)
1 (0/0) ymodem.org
2 (0/0) wyrm.org | It's not what you think, it's what I think
3 (0/0) wyrm.org | Just the media
4 N (3/3) w's timeline
5 (0/0) The Obscuritory
6 N (1/1) Nuclear Monster
7 N (48/48) LWN.net
8 N (2/2) OpenBSD Journal
9 (0/0) Pleroma News
10 (0/0) FreeBSD News Flash
11 N (5/5) XML.com Atom feed for articles and news items
12 N (2/2) Going Terribly
q:Quit ENTER:Open n:Next Unread r:Reload R:Reload All A:Mark Read C:Mark All Read /:Search ?:Help
Yours will look different depending on what feeds you follow. Basic usage is to use the arrow keys to find a feed you want to read → hit 'enter' to open it → find the article that you want to read → hit 'enter' to open the summary (or whatever the feed gives you). Once you're done, you can do things like press 'n' to jump to the next unread article (even if it's in a different feed), 'q' to escape from the article you're reading, 'o' to open the link in the browser we defined earlier (if there's more than one link, they're presented as a numbered list and you can use the number keys to open those directly). The context help at the bottom of the screen is your friend.
If you open an item that contains a podcast link, you will see 'e' for 'enqueue'. This puts the link to the media file into podboat's queue for you to listen to later.
Whenever now becomes later, you close newsboat (or open it up in a different terminal) and open podboat. The interface is very similar, but instead of a bunch of news feeds, you'll see all of the media you queued up.
Queue (0 downloads in progress, 1 total) - 0.00 KB/s total - 2 parallel downloads
1 [ 0.0MB/ 0.0MB] [ 0.0 %] [ 0.00 KB/s] queued https://anchor.fm/s/341062cc/podcast/play/5264296
q:Quit d:Download c:Cancel D:Delete P:Purge Finished a:Toggle Automatic Download p:Play m:Mark as Finished ?:Help
From here you can press 'd' to download whichever podcast you've highlighted and 'p' to play it. Playing the file will use the media player we set up earlier, mpv. This is not an mpv guide, but basic usage is 'p' to pause, left and right arrows to skip a few seconds backward and forward, and 'q' to quit. Once you're done with the podcast, you can use capital 'D' to delete it (or you could keep it around if that's what you want to do).
And that's it. It looks complicated because there are a lot of moving parts, but they all fit together in a way that makes sense once you start digging into it. There are a lot more features here in all of these programs that I haven't touched on (like tagging and queries to sort your feeds). I strongly recommend reading the fantastic manuals and creating your own workflow.