The Newsboat RSS Feedreader

Newsboat has been tested on Linux (with glibc and musl-libc), FreeBSD and macOS.

NetBSD is currently not supported, due to technical limitations in the iconv() implementation.

"Newsboat" is a play on the name of its ancestor, "Newsbeuter". They’re spelled quite differently, but sound similar. ("Newsbeuter" is a pun on German word "wildbeuter"; "newsboat" is an English word.)

Newsboats were the vessels that collected and delivered news shuffling between boats in the port. Newsboat the program will collect the news for you, just like its namesakes did back in the day.

Newsboat binaries are available in a number of repositories:

To add feeds to Newsboat, you can simply add one feed URL per line to the ~/.newsboat/urls configuration file:

You can also import an OPML file by running newsboat -i blogroll.opml

Feeds with restricted access

If you need to add URLs that have restricted access, simply provide username/password:

In case there is a @ in the username, you need to write it as %40.

In order to protect usernames and passwords, make sure to restrict read access for ~/.newsboat/urls to you and optionally your group:

Newsboat makes sure to not display usernames and passwords in its user interface.

Local files as feeds

You can also configure local files as feeds, by prefixing the local path with file:// and adding it to the urls file:

The main UI of Newsboat consists of three views

Feed List View → Article List View → Article View

You can drill down those views by pressing Enter and move to the previous one by pressing q. Pressing q on the Feed List View — or pressing Q from anywhere — closes Newsboat.

You can also search articles' title or content by pressing / on the Feed List View or the Article List View. On the Feed List View all articles of all feeds are taken into account. On the Article List View the articles of the current feed are taken into account. When opening an article from a search result dialog, the search phrase is highlighted.

Feed List View

When you start Newsboat, it presents you with a list of feeds that you added previously.

You can now:

Article List View

After you entered a feed, you can see the list of available articles by their title. A N on the left indicates that an article wasn’t read yet.

You can now:

Article View

On an article you can scroll through the text and read it. Each link in the article has a number next to it.

You can now:

An example configuration looks like this

Many of Newsboat’s options expect strings as arguments, be it commands, passwords, dialog titles, URLs etc. Some options even take multiple strings at once. These strings can contain spaces, which might confuse Newsboat since it already uses spaces to separate option names from option arguments.

To help Newsboat understand your intent, put such strings into double quotes:

What if you need a double quote inside a string? Escape it with a backslash:

And what about the backslash itself? Escape it, too! Suppose you have a program called my favourite pager, and you want to view articles with it. Newsboat ultimately passes commands to the shell, and shell expects spaces to be escaped if you want them preserved. But since Newsboat interprets backslashes, you have to add another layer of escaping. Thus, you end up with a command like this:

It is also 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 used. This works like backtick evaluation in Bourne-compatible shells and allows users to use external information from the system within the configuration.

Backticks and # characters can be escaped with a backslash (e.g. \` and \#). In this case, they are replaced with literal ` or # in the configuration.

You can bind a key to an operation with the bind-key configuration command. You can specify an optional dialog. This is the context in which the key binding is active.

The syntax for a key binding looks like this:

Key

Lowercase keys, uppercase keys and special characters are written literally.

Key combinations with Ctrl are written using the caret ^. For instance Ctrl-R equals to ^R. Please be aware that all Ctrl-related key combinations need to be written in uppercase.

The following identifiers for special keys are supported:

Operation

An operation gets executed when pressing the corresponding key. For a complete list of available operations see Newsboat Operations and Podboat Operations.

Dialog

A dialog is a context in which the key binding is active. Available dialogs are:

It is possible to configure custom color settings in Newsboat. The basic configuration syntax is:

This means that if you configure colors for a certain element, you need to provide a foreground color and a background color as a minimum. The following colors are supported:

The default color means that the terminal’s default color will be used. The color<n> color name (where <n> is a decimal number not starting with zero) can be used if your terminal supports 256 colors (e.g. gnome-terminal, or xterm with TERM set to xterm-256color). Newsboat contains support for 256 color terminals since version 2.1. For a complete chart of colors and their corresponding numbers, please see https://www.calmar.ws/vim/256-xterm-24bit-rgb-color-chart.html.

Optionally, you can also add one or more attributes. The following attributes are supported:

Currently, the following elements are supported:

The default color configuration of Newsboat looks like this:

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

If the newsboat directory exists under XDG_CONFIG_HOME, then Newsboat will use XDG directories (creating the data directory if necessary). Otherwise, Newsboat will default to ~/.newsboat.

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

Newsboat and Podboat also create "lock files". These prevent you from starting two instances of the same program, and thus from corrupting your data. Newsboat and Podboat remove these files when you quit the program, so there is no need to copy them anywhere — just be aware of them in case you write scripts that work with cache.db or queue. By default, lock files are located as follows:

Newsboat places the lock file next to the cache file, so if you specify cache-file setting or pass --cache-file command-line argument, the path to the lock file will change too. Podboat, on the other hand, always places its lock file as shown above.

Newsboat is a fork of Newsbeuter, so the migration from the latter is partially automated. Simple enough configurations will be transferred without any user intervention, while more complicated ones might require a little tweaking afterwards.

To prevent data loss, please check the results before deleting your old configuration. Pay extra attention to files that you include in your configuration—​you’d probably want to manually copy them over to Newsboat directories, and possibly update the include paths.

Migration from Newsbeuter is attempted on startup if the following conditions are met:

Newsboat first tries to migrate an XDG configuration, and if that fails, it tries the dotdir one. If that fails as well, Newsboat proceeds with the startup as usual.

XDG migration checks that:

If both conditions are met, Newsboat tries to create its XDG dirs (aborting the migration if that fails), then copies the following files: urls and config from config dir; cache.db, queue, history.search, history.cmdline from data dir.

Dotdir migration checks that ~/.newsbeuter/ is readable and executable, and ~/.newsboat/ doesn’t exist. If those conditions are met, it tries to create ~/.newsboat/ (aborting the migration if that fails), then copies the following files: urls, cache.db, config, queue, history.search, history.cmdline.

There’s one scenario where the process breaks: if you have an XDG configuration for Newsbeuter, ~/.newsboat/ exists and ~/.newsboat/urls doesn’t exist, then Newsboat will migrate XDG files and proceed, ignoring the dotdir. Please don’t confuse the poor program like that!

The vast amount of RSS feed readers allows the export of subscriptions via OPML files. OPML is an XML file format that was designed to save outlines, and has found its primary use in the import and export of feed subscriptions between different RSS feed readers.

The best thing to start with is to export your subscriptions from the old reader. Usually, RSS feed readers have appropriate menu items available to do so.

Snownews 1.7+ stores its subscriptions natively in OPML, in ~/.config/snownews/urls.opml. Earlier versions provide an export script:

To export the subscription list from raggle, the following command is necessary:

You can then import subscriptions into Newsboat:

Don’t worry, Newsboat won’t destroy your existing configuration, or add subscriptions more than once: every URL that is added to the subscription list is checked before whether it is already in the list, and is only added if not. This makes it possible to merge several OPML files into your subscription list.

If your old RSS feed reader was able to structure your subscriptions in hierarchies, and reflected this structure in the exported OPML file, Newsboat doesn’t throw away this information (although it doesn’t support hierarchies), but generates tags from it. Tags are Newsboat’s way of organizing subscriptions in a non-hierarchical way. More information on the use of tags can be found below.

Imagine the following folder hierarchy:

Subscriptions found in the folder "Private" will be tagged with "Private", subscriptions in the folder "International" will be tagged with "News" and "News/International", subscriptions in the folder "Erlang" will be tagged ith "IT", "IT/Programming" and "IT/Programming/Erlang", and so on. This means that when you select the tag "Programming" in Newsboat, you will see all subscriptions that were in the "Programming" folder or one of its subfolders before. This means that you will lose virtually nothing of your previously configured structure.

The Old Reader is a successor to Google Reader. In order to use it, you first need to configure the proper URL source:

In addition, Newsboat needs to know your The Old Reader username and password so that it can authenticate with the service:

Note that double quotes and backslashes in your password should be escaped.

See also oldreader-passwordfile, oldreader-passwordeval, and Passwords for external APIs.

After setting these configuration values, you can start Newsboat. It will authenticate with The Old Reader and download your subscription list.

When you mark single items or complete feeds as read, Newsboat will synchronize this information directly to The Old Reader. This, of course, includes opening articles. Toggling read articles back to "unread" is also communicated to The Old Reader.

In addition, The Old Reader provides the ability to "star" and to "share" articles. Starred articles are basically bookmarks, while shared articles are shown to people that follow your The Old Reader account. Newsboat allows the use of this feature by mapping its powerful "flags" to the "star"/"unstar" resp. "share"/"unshare" operations.

In order to use this mapping, all you need to do is to configure the flags that shall be used:

After that, use these flags when you edit flags for an article, and these articles will be starred resp. shared.

By default, Newsboat also shows The Old Reader "special feeds":

You can disable these feeds by setting the following configuration variable:

The Old Reader’s folders are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

NewsBlur is a successor to Google Reader. To use it, set your urls-source:

Then, configure your NewsBlur credentials:

Note that double quotes and backslashes in your password should be escaped.

See also newsblur-passwordfile, newsblur-passwordeval, and Passwords for external APIs.

Finally, set a path to the file where Newsboat can store the HTTP cookies:

When you start Newsboat, it will download the feeds that you configured in NewsBlur. Please take a closer look at the configuration commands for what you can configure in Newsboat regarding NewsBlur.

NewsBlur’s folders are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

FeedHQ is a successor to Google Reader. Configuration basically works the same as with The Old Reader.

First, set your urls-source:

Then, configure your FeedHQ credentials:

Note that double quotes and backslashes in your password should be escaped.

See also feedhq-passwordfile, feedhq-passwordeval, and Passwords for external APIs.

If you’re using a standalone instance, you should add one more setting:

When you start Newsboat, it will download the feeds that you configured in FeedHQ. Please take a closer look at the configuration commands for what you can configure in Newsboat regarding FeedHQ.

FeedHQ’s folders are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

Bazqux uses "Google Reader API", which is also used by other readers like FeedHQ. Thus, one can leverage Newsboat’s support for FeedHQ (described above) to synchronize with Bazqux:

See Passwords for external APIs for other, more secure ways to store your password.

Supported since Newsboat 2.24.

FreshRSS is a self-hosted feed reader that also uses a "Google Reader API", but is incompatable with the FeedHQ API. To use FreshRSS support, ensure that API access is enabled in the Authentication settings for your server, and that you have set an API password for your user Profile. Then point Newsboat to your server:

See Passwords for external APIs for other, more secure ways to store your password.

Newsboat will request 20 articles by default. Change this with e.g.

FreshRSS provides the ability to "favourite"/"star" articles. Starred articles are basically bookmarks. Newsboat allows the use of these features by mapping its flags to the "star" operation.

In order to use this mapping, you need to configure the flag that should be used:

After that, use this flag when you edit flags for an article, and these articles will be starred.

By default a "Starred Items" feed is included in the feed list. This can be removed with:

FreshRSS categories are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

Newsboat can be used to synchronize with Tiny Tiny RSS installations. Tiny Tiny RSS is a web-based and (optionally) multi-user feed reader.

If you want to use Tiny Tiny RSS support, don’t forget to activate the external API support in your preferences.

To use Tiny Tiny RSS support, you need to configure a few things. First of all, Newsboat needs to know that you want to use Tiny Tiny RSS and which installation exactly:

In addition, it requires username and password for authentication:

Note that double quotes and backslashes in your password should be escaped.

See also ttrss-passwordfile, ttrss-passwordeval, and Passwords for external APIs.

Tiny Tiny RSS provides two modes of usage: single-user mode and multi-user mode. Newsboat needs to know about this, too: in single-user mode, authentication is done via Basic HTTP authentication, while in multi-user mode, authentication is done against Tiny Tiny RSS itself.

If Tiny Tiny RSS is configured in multi-user mode and still deployed behind an additional HTTP-BasicAuth, the required username and password (which may deviate from ttrss-login and ttrss-password) can be specified in the user-part of the url like this:

With these settings, Newsboat should be able to connect to Tiny Tiny RSS and download your subscribed feeds. Articles or even complete feeds that you marked as read are synchronized directly to Tiny Tiny RSS.

Tiny Tiny RSS provides the ability to "star" and to "publish" articles. Starred articles are basically bookmarks, while published articles can be retrieved via a public RSS feed. Newsboat allows the use of these features by mapping its flags to the "star" and "publish" operations.

In order to use this mapping, you need to configure the flags that shall be used:

After that, use these flags when you edit flags for an article, and these articles will be starred resp. published.

TT-RSS folders are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

Supported since Newsboat 2.10.

ownCloud News and nextCloud News implement the same protocol, so Newsboat treats them as equivalent. Instructions below apply to both.

First, set your urls-source to ocnews and tell Newsboat where to find your ownCloud instance:

Username and password are required:

See also ocnews-passwordfile, ocnews-passwordeval, and Passwords for external APIs.

ownCloud News API uses HTTP basic auth, therefore running ownCloud with SSL is highly recommended. If for any reason you don’t want Newsboat to verify the hostname of your instance against the hostname specified in the SSL certificate you’re using, just say so:

If you see intermittent "Authentication failed" errors, try configuring memory caching. That should improve the responsiveness of the API and fix the errors.

ownCloud News provides the ability to "star" articles; starred articles are basically bookmarks. Newsboat allows the use of this feature by mapping user-specified flag to the "star" operation.

In order to use this mapping, you need to configure the flag that shall be used:

OwnCloud News' folders are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

Supported since Newsboat 2.10.2.

Inoreader is a successor to Google Reader.

To use Newsboat with Inoreader, you should first get an Inoreader Pro subscription and register your own application. This is needed because app credentials have to be kept secret, and Newsboat developers don’t want to operate a proxy needed to achieve that.

Please note that API requests to Inoreader are rate-limited, so you might have problems reloading a lot of feeds, or doing so often. Keep this in mind when enabling auto-reload or lowering reload-time.

With app ID and key in hand, tell Newsboat you’d like to use Inoreader:

In addition, Newsboat needs to know your Inoreader username and password so that it can authenticate with Inoreader. Note that this is NOT your login with your Google or Facebook account. If you use one of those to login to Inoreader, you have to create a username and password in Inoreader Preferences > Profile

Note that double quotes and backslashes in your password should be escaped.

See also inoreader-passwordfile, inoreader-passwordeval, and Passwords for external APIs.

After setting these configuration values, you can start Newsboat. It will authenticate with Inoreader and download your subscription list. If you use "folders" in Inoreader to organize your feeds, Newsboat will make them available via its "tags" capability: each feed is tagged with the name of the folder in which it resides. You can select and filter feeds by tags; see Tagging and Filter Language sections for details.

When you mark single items or complete feeds as read, Newsboat will synchronize this information directly to Inoreader. This, of course, includes opening articles. Toggling read articles back to "unread" is also communicated to Inoreader.

In addition, Inoreader provides the ability to "star" and to "share" articles. Starred articles are basically bookmarks, while shared articles are shown to people that follow your Inoreader account. Newsboat allows the use of this feature by mapping its powerful "flags" to the "star"/"unstar" resp. "share"/"unshare" operations.

In order to use this mapping, all you need to do is to configure the flags that shall be used:

After that, use these flags when you edit flags for an article, and these articles will be starred resp. shared.

By default, Newsboat also shows Inoreader "special feeds":

You can disable these feeds by setting the following configuration variable:

Supported since Newsboat 2.21.

Miniflux is a "minimalist and opinionated feed reader" that is self-hostable.

Newsboat can synchronize with Miniflux installations as an alternative to the web front-end.

To configure Miniflux support, set the urls-source option and provide the url to the Miniflux instance to be used:

In addition, Miniflux requires username and password for authentication:

Note that double quotes and backslashes in your password should be escaped.

See also miniflux-passwordfile, miniflux-passwordeval, and Passwords for external APIs.

The Miniflux backend will default to using the basic HTTP authentication method, since Newsboat sends extraneous requests when trying to determine the appropriate method automatically. If your Miniflux instance uses a special setup that doesn’t function with basic authentication, it may be necessary to explicitly set the http-auth-method variable in the configuration.

Unlike with other backends, Miniflux’s starring/bookmarking feature is not currently supported in Newsboat.

Miniflux categories are converted into Newsboat tags. You can select and filter feeds by tags; see Tagging and Filter Language for details.

This mode provides one-way synchronization of subscriptions from the online service to Newsboat. In other words, Newsboat will know what feeds you’ve subscribed to, but the online service won’t know what feeds you’re reading in Newsboat.

This mode works with any service that publishes your subscriptions in OPML format.

To enable this mode, you need to set an appropriate URLs source and then tell Newsboat where to get the OPML file(s):

There are a number of ways to specify a password, each represented by a separate setting. Newsboat looks for settings in certain order, and uses the first one that it finds. The exact order is described below.

Settings are prefixed by API names; e.g. newsblur-password, feedhq-passwordeval. All APIs support all the settings, so examples below use REMOTEAPI for prefix. Replace it with the name of the remote API you use.

The first setting Newsboat checks is REMOTEAPI-password. It should contain the password in plain text.

The second setting Newsboat checks is REMOTEAPI-passwordfile. It should contain a path to a file; the first line of that file should contain the password in plain text. If the file doesn’t exit, is unreadable, or its first line is empty, Newsboat will exit with an error.

The third setting Newsboat checks is REMOTEAPI-passwordeval. It should contain a command that, when executed, will print out the password to stdout. stderr will be passed through to the terminal.

If the first line of command’s output is empty, or the command fails to execute, Newsboat will exit with an error. This is the most versatile of all the options, because it lets you emulate every other and more; let’s look at it in more detail.

For example, a user might want to store their password in a file encrypted by GPG. They create the file like that:

They enter their password, press Enter, and finish the command by pressing ^D (Control and d simultaneously). Then, they specify in their Newsboat config:

Now every time they start Newsboat, GPG will be ran. It’ll probably ask for keyring password, then decrypt the file, and pass its contents to Newsboat, which will use it to authenticate with the remote API.

Note that Newsboat will keep the password in memory the entire time Newsboat is running. Other programs might be able to dump the memory and obtain the password. We don’t currently have any protection from that; patches are welcome.

The user might use any other command here; for example, they could fetch the password from GNOME keyring, KeePass, or somewhere else entirely. The possibilities are truly endless.

If no of the aforementioned settings were found, Newsboat will ask the user for the password using an interactive prompt. If the password that the user enters is empty, Newsboat will give up and exit with an error.

Newsboat comes with the possibility to categorize or "tag", as we call it, RSS feeds. Every RSS feed can be assigned 0 or more tags. Within Newsboat, you can then select to only show RSS feeds that match a certain tag. That makes it easy to categorize your feeds in a flexible and powerful way.

Usually, the 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, you must use quotes (") around the tag (see example below). An example urls file may look like this:

When you now start Newsboat with this configuration, you can press "t" to select a tag. When you select the tag "news", you will see all three RSS feeds. Pressing "t" again and e.g. selecting the "conspiracy" tag, you will only see the https://blog.fefe.de/rss.xml?html RSS feed. Pressing "^T" clears the current tag, and again shows all RSS feeds, regardless of their assigned tags.

A special type of tag are tags that start with the tilde character (~). When such a tag is found, the feed title is set to the tag name (excluding the ~ character). These type of tags are ignored when any kind of "first tag" property is used. With this feature, you can give feeds any title you want in your feed list:

Another special type of tag are tags that start with the exclamation mark (!). When such a tag is found, the feed is hidden from the regular list of feeds and its content can only be found through a query feed.

In this example, the first two feeds won’t appear in the feedlist, but their articles will still be accessible through the query feed titled "News from around the globe". The "hidden" tags in this example don’t even have names, because their only use is to hide the feed that they’re tagging.

Newsboat contains support for Snownews extensions. The RSS feed readers Snownews and Liferea share a common way of extending the readers with custom scripts. Two mechanisms, namely "execurl" and "filter" type scripts, are available and supported by Newsboat.

An "execurl" script can be any program that gets executed and whose output is interpreted as RSS feed, while "filter" scripts are fed with the content of a configured URL and whose output is interpreted as RSS feed.

The configuration is simple and straight-forward. Just add to your urls file configuration lines like the following ones:

The first line shows how to add an execurl script to your configuration: start the line with exec: and then immediately append the path of the script that shall be executed. If this script requires additional parameters, simply use quotes (see Using Double Quotes for details):

The second line shows how to add a filter script to your configuration: start the line with filter:, then immediately append the path of the script, then append a colon (:), and then append the URL of the file that shall be fed to the script. Again, if the script requires any parameters, simply quote the whole thing:

In both cases, the tagging feature as described above is still available:

If you need to write your own extension, see this short guide for an introduction. A collection of existing scripts and filters might help, too.

Newsboat comes with an example exec script which shows one way to generate an RSS channel. It also includes a way to see which exact arguments are passed to the script by Newsboat. This example can be found in the doc/examples subdirectory.

This feature lets you save links from the article list, the article view, and the URL view. The actual bookmarking is performed by a program that you specify via the bookmark-cmd setting; Newsboat merely supplies the data.

To bookmark the currently selected item, press ^B (invoking the bookmark operation), and Newsboat will ask you for:

(If you find that the above preset values always work for you, enable bookmark-autopilot to avoid being asked anything.)

After that, the program configured via bookmark-cmd is executed. It is given four arguments, the same ones and in the same order as described above. The program then does the actual bookmark saving, e.g. writing the bookmark into an external file, or storing it to a del.icio.us account.

If everything goes OK, the program simply exits. In case something goes wrong, the program writes out an error message to stdout as a single line. This error message is then presented to the user from within Newsboat. At the moment, Newsboat doesn’t care about the exit code of the program; only its output is used to determine success.

Some bookmarking commands are interactive, e.g. they might want you to select a category for your bookmark, or a Mastodon account from which to share the bookmark. Oftentimes you can specify defaults for these, but if you can’t, enable bookmark-interactive: it will make Newsboat relinquish the terminal to the bookmarking program. You’ll be able to make all the changes there, and will return to Newsboat once the bookmarking program exits.

Newsboat comes with an example plugin, doc/examples/example-bookmark-plugin.sh, which implements a simple tab-separated bookmark file. You can use that as a starting point to write your own bookmarking program.

Like other text-oriented software, Newsboat contains an internal commandline to modify configuration variables ad hoc and to run own commands. It provides a flexible access to the functionality of Newsboat which is especially useful for advanced users.

To start the commandline, type ":". You will see a ":" prompt at the bottom of the screen, similar to tools like vi(m) or mutt. You can now enter commands. Pressing the "Enter" key executes the command (possibly giving feedback to the user) and closes the commandline. You can cancel entering commands by pressing the "Esc" key. The history of all the commands that you enter will be saved to the history.cmdline file, stored next to the cache.db file. The backlog is limited to 100 entries by default, but can be influenced by setting the history-limit configuration variable. To disable history saving, set the history-limit to 0.

The commandline provides you with some help if you can’t remember the full names of commandline commands. By pressing the "Tab" key, Newsboat will try to automatically complete your command. If there is more than one possible completion, you can subsequently press the "Tab" key to cycle through all results. If no match is found, no suggestion will be inserted into the commandline. For the set command, the completion also works for configuration variable names.

In addition, some common key combination such as "Ctrl-G" (to cancel input), "Ctrl-K" (to delete text from the cursor position to the end of line), "Ctrl-U" (to clear the whole line) and "Ctrl-W" (to delete the word before the current cursor position) were added.

Please be aware that the input history of both the command line and the search functions are saved to the filesystems, to the files history.cmdline resp. history.search (stored next to the cache.db file). By default, the last 100 entries are saved, but this can be configured (configuration variable history-limit) and also totally disabled (by setting said variable to 0).

Currently, the following command line commands are available:

Quit Newsboat.

Alias for quit.

Export the currently selected article to a plain text file. This works in the article list and in the article view.

Set configuration variable <variable> to <value>. If no value is specified, the current value is printed out. Specifying a ! after the name of boolean configuration variables toggles their values, a & directly after the name of a configuration variable of any type resets its value to the documented default value.

Only display feeds with the tag <tagname>.

Search for a feed whose name contains the case-insensitive substring.

Load the specified configuration files. This allows it to load alternative configuration files or reload already loaded configuration files on-the-fly from the filesystem.

Save current internal state of configuration to file, so that it can be instantly reused as configuration file.

Run a keybind operation in the current context.

Jump to the entry with the index <number> (usually seen at the left side of the list). This currently works for the feed list, article list, tag selection and filter selection forms.

Newsboat provides a powerful filter language that enables the user to filter the content of many dialogs, such as the feed list or the article list. The basic concept is that every feed and every article has a number of attributes which can then be compared with user-supplied values, and these comparisons and be logically AND’ed, OR’ed and grouped.

Examples for simple filter expressions are:

Logically connecting and grouping such expressions looks like in the following examples:

The possibilities for combining such queries is endless, sky (actually: the available memory) is the limit.

To filter your feeds, press "F" in the feed list, enter your filter expression, and press "Enter". To clear the filter, press "Ctrl-F". To filter the articles in the article list, press "F", enter your expression, and press "Enter". Clearing the filter works the same as before. Be aware that only certain attributes work in both dialogs. The table below lists all available attributes and their context, i.e. an attribute that belongs to a feed can only be matched in the feed list, while an attribute that belongs to an article can only be matched in the article list.

Note that it’s also possible to filter for feed attributes when you query for article attributes. This is because every article is internally linked to the feed from which it was downloaded.

Sometimes, a user is confronted with certain content they don’t want to read, e.g. on topics the user is not interested in or articles written by certain people. In Usenet, such functionality within software is traditionally called a "killfile", i.e. based on the content of this "killfile", articles that match certain conditions do not get displayed and are not presented to the user at all.

In Newsboat, such a "killfile" can be implemented on a per-article basis via the configuration file. The most important configuration command for this is ignore-article:

It takes two parameters. The first one is either:

The second argument is a filter expression for an article, probably in double quotes to preserve spaces inside. If Newsboat hits an article in the specified RSS feed that matches the specified filter expression, then this article is ignored and never presented to the user. The configuration itself can contain as many ignore-article commands as desired.

You can also specify the way an article is ignored. There are two ways available:

Both modes have their advantages and disadvantages: while the download ignore mode saves some storage, you cannot simply "undo" the ignore by removing it from the configuration file: if an ignored article has already vanished from a feed, it won’t reappear. On the other hand, the display ignore mode requires some more space, but has the advantage that an ignore can be "undone" by removing the ignore-article configuration command from the configuration.

The default ignore mode is "download". You can set the ignore-mode in the configuration file:

Query feeds are a mechanism of Newsboat to define custom "meta feeds" by using Newsboat’s built-in filter language. A query feed is a feed that is aggregated from all currently downloaded articles of all feeds. To narrow down the set of articles, the user has to specify a filter. Only articles that match this filter are added to the query feed.

A query feed is updated whenever it is entered in the feed list. When you change the unread flag of an article, this is reflected in the feed where the article was originally fetched. If you want query feeds to be updated at startup, set prepopulate-query-feeds to yes.

To define a query feed, the user has to add a line to the urls file in the following format:

The query: in the beginning tells Newsboat that it’s a query feed, <name of feed> specifies the name under which the query feed shall be displayed in the feed list, and <filter expression> is the filter expression that shall be used. Like every other feed, a query feed can be tagged to organize it like a regular feed.

This feature is often used to create a feed that contains all unread articles:

Note the use of double quotes to preserve spaces in the filter expression.

If you want to combine several feeds to one single feed, a good solution is to tag the feeds that you want to combine with one certain tag, and then create a query feed that only displays articles from feeds with that certain tag:

In this example, the feeds https://domain1.tld/feed.xml and https://domain2.tld/?feed.rss are aggregated into the query feed named "tag1 Articles", but the feed https://domain3.tld/feeds.rss is not.

Basically, the possibility of what can be realized with query feeds is only limited by what can be queried from articles and feeds with the filter language and by your creativity.

To support custom categorization of articles by the user, it is possible to flag an article. A valid flag is any character from A to Z and from a to z. Every article can be flagged with up to 52 different flags, i.e. every letter from the Roman alphabet in upper and lower case. Flagging is easy: just select an article in the article list, or enter the article view, and press "Ctrl-E". This will start the flag editor. By pressing "Enter", the new flags are saved. You can cancel by pressing the "Esc" key.

The flags of an article can be used in every filter expression. The flags of an article are always ordered, and when new flags are added, ordering is immediately restored. This behaviour can also be relied upon when querying articles via the filter language.

If an article contains one or more flags, it is marked with an "!" in the article list. In the article view, all flags (if available) are listed.

Newsboat comes with a -x option that indicates that commands added as arguments to the command line shall be executed. Currently, the following commands are available:

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.

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.

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

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

Examples:

Newsboat supports the highlighting of text in the feed list, the article list and the article view, using regular expressions to describe patterns to be highlighted. The command syntax goes like this:

Valid values for <target> are feedlist, articlelist, article and all. When specifying all, the matching will be done in all three views. The <regex> must be a POSIX extended regular expression, which will be matched case-insensitive against the text. If multiple highlight matches overlap, the style of the later specified highlight rule will be applied. <fgcolor> and <bgcolor> specify the foreground color resp. the background color of the matches. You can also specify 0 or more attributes. You can find a list of valid colors and attributes in the [_configuring_colors].

Examples for possible highlighting configurations are:

Note the use of double quotes to preserve spaces in the regular expressions.

Newsboat supports an advanced concept of dialogs. Previously, all dialogs (feed list, article list, article view) were internally laid out as a pure stack. In 2.0, this changed: all dialogs are managed in a list, and the user can jump to another, previously opened dialog from everywhere. This allows a user to open more than one article list, more than one article view, etc., and switch between them without closing them.

The main dialog for this feature can be reached by pressing the "v" key. This opens the list of open dialogs. From there, the user can switch to another dialog by selecting the appropriate entry and pressing "Enter", or can close open dialogs by selecting them and pressing "Ctrl-X".

Bindings created with bind-key can only execute a single operation, like open or quit. To execute multiple operations, one has to define a so-called "macro". To invoke the macro, the user presses the macro prefix ("," by default) and then the macro’s key. It’s easier to explain with some examples:

Here, we define two macros. Now when the user types ",k", Newsboat will enter the current feed, reload it, and go back to the feedlist. If the user types ",o", Newsboat will open current article in the external browser, and also mark it read. Note that macros can have a description which will be displayed in the help dialog when the user presses "?".

Macros can invoke any of Newsboat’s operations. Keep in mind that some operations only make sense in certain situations, e.g. reload doesn’t make sense while viewing an article. If you try to execute an operation that is not supported by the current dialog, it will be ignored.

The macro prefix can be changed from the default "," to another key, e.g. "+" (if you don’t unbind the default "," you’re left with two macro prefixes):

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, though an external media player is needed for playback. 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.

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!

The following sections present two different ways to handle podcasts with Newsboat.

During development and testing, you might want to run a second copy of Newsboat, operating with different config, URLs list or cache file. This can be achieved by creative use of XDG environment variables. This approach is not beautiful, but it works.

First of all, you will need to create a directory to store the data. Let’s call it test:

Note that we also create a subdirectory called newsboat; this is required to satisfy XDG specification. ATTENTION: if this subdirectory is absent, Newsboat will attempt to run on your live data!

You can now create config and urls files inside test/newsboat; you can also copy cache.db if you don’t want to start with a fresh one.

When the files are ready, you can invoke Newsboat as follows:

(This will look newsboat binary up in your PATH; if you’ve just built your own, use ./newsboat instead, or provide a full path.)

By modifying the environment in which Newsboat runs you also modify environments of all the programs that Newsboat starts; that includes filters and external HTML renderers. If they rely on XDG_* variables, they will look for things in test directory and might fail.

For filters, you should either copy the files they need to test, or invoke them in such a way that they don’t look in XDG directories at all.

For renderers, you can work around the issue by undoing the modifications to environment, e.g.:

As already said: not beautiful, but gets the job done.

This section was written by Elrond, originally for Newsbeuter.

SQLite, the db used by Newsboat, supports triggers. These are small snippets of SQL that get executed inside the database by the database engine. They’re stored inside the db and the normal user (including Newsboat itself) doesn’t see them. Just the db seems to do some magic: Like changing some values when you change another value.

So what is this good for when looking at Newsboat? Well, first off, it’s a hack. The real answer should be to use application logic (do it inside Newsboat, not in the db). So: Don’t use this, unless you know, what you’re doing, and unless you have some sort of backup.