Can I sync Newsboat read-state across multiple machines?

Yes. Newsboat supports Miniflux, FreshRSS, Nextcloud News, The Old Reader, and Tiny Tiny RSS via the 'urls-source' config option. Set the API endpoint and credentials and Newsboat syncs read/unread state on each reload.

How do I open articles in a GUI browser from the terminal?

Set 'browser "firefox %u"' in config. On Wayland ensure WAYLAND_DISPLAY is exported in your shell environment; on X11 ensure DISPLAY is set. You can also use macros to switch browsers per-article.

Is the urls file the only place to add feeds?

No. You can use the 'include' directive to split feeds across multiple files, and you can import an OPML file on first run with 'newsboat -i feeds.opml' which appends entries to your urls file.

How do I stop a particularly noisy feed from flooding the list?

Set per-feed limits with the 'max-items' option in config, or use a 'filter' rule to drop articles matching a pattern. You can also mark the entire feed as read automatically with an 'ignore-article' rule.

Does Newsboat work over SSH on a headless server?

Yes, it is a fully terminal application with no display dependency. Run it inside tmux or screen on the server so it continues refreshing even when you disconnect.

Use Newsboat — RSS in the Terminal

Newsboat is a fast, keyboard-driven RSS/Atom reader that lives entirely in your terminal. It stores feeds in a plain-text file, keeps a local SQLite cache, and ships with podboat — a companion podcast downloader. If you spend most of your day in a terminal, Newsboat fits naturally alongside tmux, vim, and mutt.

Installation

Debian / Ubuntu

sudo apt update && sudo apt install newsboat

Fedora / RHEL / Rocky

sudo dnf install newsboat

Arch Linux

sudo pacman -S newsboat

Newsboat 2.28+ is in all current LTS/stable repos. Check newsboat --version after install; anything below 2.24 is missing useful macro features.

The URLs File

Newsboat reads its feed list from ~/.config/newsboat/urls. One URL per line. Tags follow the URL on the same line, prefixed with a tilde.

mkdir -p ~/.config/newsboat
nano ~/.config/newsboat/urls

A minimal starting file:

https://feeds.feedburner.com/linuxjunkies ~linux ~howto
https://lwn.net/headlines/rss ~linux ~news
https://archlinux.org/feeds/news/ ~linux ~arch
https://www.phoronix.com/rss.php ~linux ~hardware
https://lobste.rs/rss ~tech ~programming
https://www.schneier.com/blog/atom.xml ~security

Tags appear as a filterable list in the left sidebar. You can have multiple tags per feed. To give a feed a custom display name, place it in double quotes before the tags:

https://lwn.net/headlines/rss "LWN.net" ~linux ~news

Adding a Podcast Feed

Podcast feeds are just RSS. Mark them with a tag so podboat can filter them later:

https://feeds.twit.tv/floss.xml "FLOSS Weekly" ~podcast ~linux

newsboat

On first run Newsboat fetches all feeds. Default key bindings are vi-style. The most important ones:

Key	Action
`r`	Reload current feed
`R`	Reload all feeds
`Enter`	Open feed / open article
`q`	Quit / go back one level
`n` / `p`	Next / previous unread article
`o`	Open article URL in browser
`m`	Toggle read/unread
`s`	Save article to file
`/`	Search within feed list or articles
`t`	Filter by tag
`?`	Show all key bindings

The Config File

All settings go in ~/.config/newsboat/config. Create it if it does not exist.

nano ~/.config/newsboat/config

A practical baseline config:

# Refresh every 60 minutes automatically
auto-reload yes
refresh-on-startup yes
reload-time 60
max-items 100

# Open articles in w3m; swap for lynx, elinks, or a GUI browser
browser "w3m %u"

# Show article count in feed list
showread yes

# Confirm before marking all as read
confirm-mark-feed-read yes

# Colour scheme (optional)
color background          default default
color listnormal          default default
color listfocus           black   yellow  bold
color listnormal_unread   default default bold
color listfocus_unread    black   yellow  bold
color info                default black   bold
color article             default default

# Feed list format: unread/total | title | last-updated
feedlist-format "%u/%t %T %?d?%d?%F? (%U)"

Custom Key Bindings

Rebind keys with bind-key. Unbind first if the key is already taken.

# Open URL in Firefox instead of the configured browser
macro o set browser "firefox %u" ; open-in-browser ; set browser "w3m %u"

# Mark all articles as read with a single keystroke
bind-key A mark-all-feeds-read

# Jump straight to next unread across all feeds
bind-key J next-unread

Macros are triggered by pressing the macro prefix key (default ,) followed by the bound key. The semi-colon separates macro commands.

Podboat: Downloading Podcasts

Podboat ships alongside Newsboat and uses the same config directory. It reads a queue file that Newsboat populates when you enqueue podcast enclosures.

Step 1 — Set the Download Directory

Add to ~/.config/newsboat/config:

podboat-auto-enqueue yes
podcast-auto-enqueue yes
download-path "~/podcasts/%n"

%n expands to the feed name, creating one folder per show. Set podboat-auto-enqueue yes only if you want every new episode enqueued automatically — it can fill a disk fast on prolific feeds.

Step 2 — Enqueue Episodes Manually

Inside Newsboat, open a podcast feed, highlight an article, and press e to add it to the podboat queue. Alternatively press E to enqueue all items in the current feed.

Step 3 — Run Podboat

podboat

Press d to start downloading the highlighted item, a to download all queued items. Podboat shows progress inline. Downloads resume if interrupted.

Dotfiles Patterns

Newsboat's config lives in two files you should version-control: urls and config. The cache (cache.db) and queue (queue) do not belong in version control.

Symlinking from a Dotfiles Repo

# Assuming your dotfiles live in ~/dotfiles
mkdir -p ~/dotfiles/newsboat
mv ~/.config/newsboat/urls    ~/dotfiles/newsboat/urls
mv ~/.config/newsboat/config  ~/dotfiles/newsboat/config

ln -s ~/dotfiles/newsboat/urls   ~/.config/newsboat/urls
ln -s ~/dotfiles/newsboat/config ~/.config/newsboat/config

A .gitignore for the Newsboat Dir

cat > ~/dotfiles/newsboat/.gitignore <<'EOF'
cache.db
cache.db.lock
queue
history.search
history.cmdline
EOF

Splitting the URLs File

If you manage a large feed list, include lets you split by category:

# In urls:
include ~/.config/newsboat/urls.linux
include ~/.config/newsboat/urls.tech
include ~/.config/newsboat/urls.podcasts

Verification

After setting everything up, force a full reload and check for errors:

newsboat -x reload

Newsboat prints a line per feed; feeds that fail show an HTTP error code or DNS failure message. Fix bad URLs in urls and rerun. You can also check the log:

newsboat --log-level=3 --log-file=/tmp/nb.log
cat /tmp/nb.log

Log levels run 1–6; level 3 captures warnings and errors without flooding the file.

Troubleshooting

Feed shows 0 articles after reload: The site may use a non-standard Content-Type. Try fetching manually with curl -L <url> and verify the XML is valid RSS or Atom.
Browser doesn't open: If you're in a remote SSH session without a display, set browser "w3m %u" or another terminal browser in the config. On Wayland, GUI browsers should work if WAYLAND_DISPLAY is set; if not, check that XDG_RUNTIME_DIR is correct.
Podboat won't download: Make sure the download-path directory exists and is writable. Podboat does not create nested directories automatically if the parent is missing.
Cache grows very large: Lower max-items per feed and run newsboat --cleanup to remove orphaned articles from the SQLite cache.
Paywalled feeds return no content: Some feeds require a cookie. Use the cookie-cache option pointing to a Netscape-format cookie file exported from your browser.