Newsboat

Newsboat is an open source news aggregator licensed under the MIT License.

Newsboat is an RSS/Atom feed reader for text terminals. RSS and Atom are a number of widely-used XML formats to transmit, publish and syndicate articles, for example news or blog articles. Newsboat is designed to be used on text terminals on Unix or Unix-like systems such as GNU/Linux, BSD or macOS.

Newsboat is a fork of abandoned Newsbeuter.

Installation

Install the newsboat package. For the development version, install the newsboat-git^AUR package.

Usage

Newsboat cannot start without any configured feeds. Feeds can be configured in ~/.newsboat/urls. Newsboat can be started from the command line with

$ newsboat

Press the ? key to see a list of all keybindings. Keybindings can be rebound, see #Configuration.

Managing feeds

Adding, removing, and tagging feeds is done by editing the urls file. By default that is ~/.newsboat/urls.

Tip: In addition to newsboat specific feeds in this section, be sure to see the Web feed article for additional options.

RSS or ATOM sources

To add URLs, open ~/.newsboat/urls with your favorite text editor and add the URLs, one per line:

http://rss.cnn.com/rss/cnn_topstories.rss
http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml

To add URLs that have restricted access via username/password, simply provide the username/password in the following way:

http://username:[email protected]/feed.rss

In order to protect username and password, make sure that ~/.newsboat/urls has the appropriate permissions. Newsboat also makes sure that usernames and passwords within URLs aren’t displayed in its user interface. In case there is a @ in the username, type it as %40 instead so that it can be distinguished from the @ that separates the username/password part from the hostname part.

To configure local files as feeds, simply prefix the local path with file:// and add it to the ~/.newsboat/urls file:

file:///var/log/rss_eventlog.xml

HTML as a source

If HTML sources can be converted to RSS via a user supplied script, newboat can both execute this script and consume the output.

This is accomplished by using the filter: prefix in the configuration file. For example, write a script that can read HTML from stdin and print out an RSS or Atom feed to stdout. Save that script to ~/.newsboat/html2rss.sh and add the following line to the urls:

filter:~/.newsboat/html2rss.sh:https://myurl.com

For several examples using this strategy, see graysky's newsboat repo.
For more discussion, see Possible to config newsboat to look at a web exposed directory and report changes #1157.

Tagging feeds

Every feed can be assigned 0 or more tags. This makes it easy to categorize your feeds as well as the ability to easily apply commands to multiple feeds at once.

Usually, the ~/.newsboat/urls file contains one RSS feed URL per line. To assign a tag to an RSS feed, simply attach it as a single word, separated by blanks such as space or tab. If the tag needs to contain spaces, use quotes (") around the tag (see example below). An example may look like this:

http://blog.fefe.de/rss.xml?html interesting conspiracy news "cool stuff"
http://rss.orf.at/news.xml news orf
http://www.heise.de/newsticker/heise.rdf news interesting

Starting Newsboat with this configuration, one can press t to select a tag. Upon selecting the tag "news", one will see all three RSS feeds. Pressing t again and e.g. selecting the "conspiracy" tag, will only show the http://blog.fefe.de/rss.xml?html RSS feed. Pressing Ctrl-T clears the current tag, and again shows all RSS feeds, regardless of their assigned tags.

Note: If the tag name contains spaces, the tag must be bounded by "

Special tags

Custom feed names

The name of a feed can be defined with a special tag in your urls file. Simply prefix the tag name with the ~ character and the tag name will become the feed name.

For example:

http://rss.cnn.com/rss/cnn_topstories.rss "~CNN Top stories"

will define the feed with feed-name "CNN Top stories"

Hidden feeds

A feed can be hidden from the regular list of feeds by prefixing the tag name with an !.

For example:

http://rss.orf.at/news.xml "!ORF News (hidden)"

The content of a hidden feed can only be found through a query feed.

Ignoring articles

There are two ways to ignore articles, delete them or not show them.

~/.newsboat/config

# ignore-mode "download" # Default: Delete them.
ignore-mode "display"    # Do not show them.

The filter can be configured like so (here in POSIX extended regular expressions):

~/.newsboat/config

ignore-article "https://feed/url" "content =~ \"tele(phone|communications)\""                     
ignore-article "https://feed/url" "title =~ \"text_1|text_2\""

Configuration

Several aspects of Newsboat’s behaviour can be configured via a configuration file which is located, by default, in ~/.newsboat/config or ~/.config/newsboat/config. This configuration file contains lines of the form:

<config-command> <arg1> ...

Color schemes

The package ships with a number of schemes in /usr/share/doc/newsboat/contrib/colorschemes/ which can be loaded with the include command like so:

include /usr/share/doc/newsboat/contrib/colorschemes/inkpot

Additional options

The configuration file can also contain comments, which start with the # character and go as far as the end of line. To enter a configuration argument that contains spaces, use quotes " around the whole argument. It’s even possible to integrate the output of external commands into the configuration. The text between two backticks ` is evaluated as shell command, and its output is put on its place instead. This works like backtick evaluation in Bourne-compatible shells and allows users to use external information from the system within the configuration.

See [1] and [2] for example configurations.

Note: To see a complete list of configuration command, consult the man page

Tips

Automatic feed reloads

Newsboat can automatically reload all feeds on startup with the following configuration:

auto-reload yes

With this setting, Newsboat also runs periodic auto-reloads – by default, every 60 minutes. The number of minutes between automatic reloads can be configured like so:

reload-time <desired number of minutes>

Alternatively, use cron or systemd to automatically reload feeds. Just add a line in your crontab, or create a systemd service/timer unit combo that issues the following command:

/usr/bin/newsboat -x reload

Loading of feeds in parallel for faster updates

By default, Newsboat will attempt to update entries in ~/.newsboat/urls in sequence however, the following setting will update them n at a time, in parallel. Adjust n to your liking.

reload-threads 100

Pass article URL to external command

A clever little hack allows one to pass the URL of an article to an external command. The idea is to use a macro to set the browser that Newsboat opens the article with to the path of some other command and then change it back afterwards.

For example, subscribers of a particular youtube channel can open the video with mpv, by doing the following:

macro y set browser "mpv %u" ; open-in-browser ; set browser "elinks %u"

Note: First press the , key, followed by the keybind to use the macro. In the example above, type , + y

Subheadings

There is another little hack that allows the user to add subheadings to sort feeds more effectively. This hack involves adding fake feeds to the urls file like so:

---Heading---

Note: the --- characters are optional but having some sort of character identifying the headings is useful for styling.

Then in ~/.config/newsboat/config, add the following two lines:

highlight feedlist "---.*---" COLOR_OF_YOUR_CHOOSING default bold
highlight feedlist ".*0/0.." default default invis

Of course, replace COLOR_OF_YOUR_CHOOSING with a newsboat supported color.

This trick can also interact with Tags by replacing ---Heading--- with:

"query:---Heading---:tags # \"Tag\""

Then tagging all the feeds below the heading with Tag.

Troubleshooting

Newsboat will not start

Newsboat cannot start without any configured feeds! To add URLs, see #Managing feeds. If that is not the problem, check to see if another instance of Newsboat is running. Newsboat issues a lock on its database so that only one instance can access it at a time; thus, attempting to open a second instance will fail.