NEWSBOAT(1) | NEWSBOAT(1) |
NAME¶
newsboat - an RSS/Atom feed reader for text terminals
SYNOPSIS¶
newsboat [-r] [-e] [-i opmlfile] [-u urlfile] [-c cachefile] [-C configfile] [-X] [-o] [-x command...] [-h]
DESCRIPTION¶
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.
OPTIONS¶
-h, --help
-r, --refresh-on-start
-e, --export-to-opml
--export-to-opml2
-X, --vacuum
--cleanup
Additionally, if the delete-read-articles-on-quit configuration is set, all read articles will be deleted (including articles of feeds which are still in the urls file).
-v, -V, --version
-i opmlfile, --import-from-opml=opmlfile
-u urlfile, --url-file=urlfile
-c cachefile, --cache-file=cachefile
-C configfile, --config-file=configfile
--queue-file=queuefile
--search-history-file=searchhistoryfile
--cmdline-history-file=cmdlinehistoryfile
-x command ..., --execute=command...
-l loglevel, --log-level=loglevel
-d logfile, --log-file=logfile
-E file, --export-to-file=file
-I file, --import-from-file=file
FIRST STEPS¶
After you’ve installed Newsboat, you can run it for the first time by typing newsboat on your command prompt. This will bring you the following message:
Error: no URLs configured. Please fill the file /home/ak/.newsboat/urls with RSS feed URLs or import an OPML file. Newsboat 2.22 usage: ./newsboat [-i <file>|-e] [-u <urlfile>] [-c <cachefile>] [-x <command> ...] [-h]
-e, --export-to-opml export OPML feed to stdout
-r, --refresh-on-start refresh feeds on start
-i, --import-from-opml=<file> import OPML file
-u, --url-file=<urlfile> read RSS feed URLs from <urlfile>
-c, --cache-file=<cachefile> use <cachefile> as cache file
-C, --config-file=<configfile> read configuration from <configfile>
-X, --vacuum compact the cache
-x, --execute=<command>... execute list of commands
-q, --quiet quiet startup
-v, --version get version information
-l, --log-level=<loglevel> write a log with a certain loglevel (valid values: 1 to 6)
-d, --log-file=<logfile> use <logfile> as output log file
-E, --export-to-file=<file> export list of read articles to <file>
-I, --import-from-file=<file> import list of read articles from <file>
-h, --help this help
--cleanup remove unreferenced items from cache
This means that Newsboat can’t start without any configured feeds.
Adding Feeds¶
To add feeds to Newsboat, you can simply add one feed URL per line to the ~/.newsboat/urls configuration file:
http://rss.cnn.com/rss/cnn_topstories.rss http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml
You can also import an OPML file by running newsboat -i blogroll.opml
Adding comments Lines that start with # can contain anything you want. Comments are ignored by Newsboat, but can serve as documentation for you. Please note, that commenting out URLs for debugging purposes might lead to unexpected data loss, see cleanup-on-quit for more details.
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:
$ chmod u=rw,g=r,o= ~/.newsboat/urls
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:
First UI Interaction¶
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 Shift + 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.
Search history The history of all your searches is saved to the filesystem, to the history.search file (stored next to the cache.db file). By default, the last 100 search phrases are stored.
You can influence how many search phrases are stored by configuring history-limit.
Feed List View
When you start Newsboat, it presents you with a list of feeds that you added previously.
You can now:
Local articles Newsboat keeps the articles that it downloads. When you start Newsboat again and reload a feed, old articles can still be read even if they aren’t in the current RSS feeds anymore. The maximum number of articles is controlled by max-items.
Caching Newsboat uses a number of measures to preserve the users' and feed providers' bandwidth through the use of conditional HTTP downloading. It saves every feed’s "Last-Modified" and "ETag" response header values (if present) and advises the feed’s HTTP server to only send data if the feed has been updated. This doesn’t only make feed downloads for RSS feeds with no new updates faster, it also reduces the amount of transferred data per request.
You can disable conditional HTTP downloading per feed by configuring always-download.
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:
Browser view Sometimes the content of an article is empty or just an abstract or short description. You can always press O to view the complete article in a browser. The default browser is lynx.
You can use your browser of choice by configuring browser.
CONFIGURATION¶
Several aspects of Newsboat can be configured via a config file, which is stored next to the urls file. A configuration line looks like this in general:
<config-command> <arg1> ...
The configuration file can contain comments, which start with the # character and go as far as the end of line.
User contrib Newsboat also comes with user contributed content like scripts and color themes. The user contributed content can be found in /usr/share/doc/newsboat/contrib/. End users are encouraged to take a look as they may find something useful.
Example¶
An example configuration looks like this
# a comment max-items 100 # such comments are possible, too browser links show-read-feeds no unbind-key R bind-key ^R reload-all
Splitting long lines into multiple ones¶
Settings such as macros and ignore-article can be quite lengthy. A long line can be broken into multiple ones using backslashes. A backslash must be the last character on the line and will immediately concatenate it with the following line. It’s important that nothing follows the \ on the same line, otherwise the \ character is treated "as is". For example:
macro p open; \ reload; quit; \ quit; \ quit -- "Opens, reloads then makes sure to quit newsboat"
Please note that a backslash only makes Newsboat ignore the following newline. It doesn’t do anything else at all. For example, this nicely formatted option:
ignore-article \
"*" \
"author =~ \"(\
John Doe| \
Mary Sue \
)\""
does not turn into this:
ignore-article "*" "author =~ \"(John Doe|Mary Sue)\""
Instead, as only newlines are removed, it turns to this:
ignore-article "*" "author =~ \"( John Doe| Mary Sue )\""
For this reason, be conscious of where you’re splitting the lines, because it might matter.
Using Double Quotes¶
TL;DR Use double quotes for strings that contain spaces or double quotes. Escape double quotes (use \") and backslashes (use \\). Don’t escape stuff outside of double quotes, and don’t use single quotes for quoting — Newsboat doesn’t support that.
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:
browser "firefox --new-tab %u"
What if you need a double quote inside a string? Escape it with a backslash:
ocnews-password "UnbalancedQuotes\"AreSoFun!"
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:
pager "/usr/bin/my\\ favourite\\ pager"
Shell Evaluation¶
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.
Escaping¶
Backticks and # characters can be escaped with a backslash (e.g. \` and \#). In this case, they are replaced with literal ` or # in the configuration.
Key Bindings¶
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:
bind-key <key> <operation> [<dialog>]
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:
Colors¶
It is possible to configure custom color settings in Newsboat. The basic configuration syntax is:
color <element> <foreground color> <background color> [<attribute> ...]
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:
color background white black color listnormal white black color listfocus yellow blue bold color listnormal_unread white black bold color listfocus_unread yellow blue bold color title yellow blue bold color info yellow blue bold color hint-key yellow blue bold color hint-keys-delimiter white blue color hint-separator white blue bold color hint-description white blue color article white black
CONFIGURATION COMMANDS¶
always-display-description (parameters: [yes/no]; default value: no)
always-download (parameters: <url> [<url>...]; default value: n/a)
article-sort-order (parameters: <sortfield>[-<direction>]; default value: date-asc)
articlelist-format (parameters: <format>; default value: "%4i %f %D %6L %?T?|%-17T| ?%t")
articlelist-title-format (parameters: <format>; default value: "%N %V - Articles in feed '%T' (%u unread, %t total)%?F? matching filter '%F'&? - %U" (localized))
auto-reload (parameters: [yes/no]; default value: no)
bind-key (parameters: <key> <operation> [<dialog>]; default value: n/a)
bookmark-autopilot (parameters: [yes/no]; default value: no)
bookmark-cmd (parameters: <command>; default value: "")
bookmark-interactive (parameters: [yes/no]; default value: no)
browser (parameters: <command>; default value: %BROWSER, otherwise lynx)
cache-file (parameters: <path>; default value: "~/.newsboat/cache.db" or "~/.local/share/cache.db" (see "Files" section))
cleanup-on-quit (parameters: [yes/no]; default value: yes)
color (parameters: <element> <fgcolor> <bgcolor> [<attribute> ...]; default value: n/a)
confirm-delete-all-articles (parameters: [yes/no]; default value: yes)
confirm-exit (parameters: [yes/no]; default value: no)
confirm-mark-all-feeds-read (parameters: [yes/no]; default value: yes)
confirm-mark-feed-read (parameters: [yes/no]; default value: yes)
cookie-cache (parameters: <path>; default value: "")
datetime-format (parameters: <date/time format>; default value: %b %d)
define-filter (parameters: <name> <filterexpr>; default value: n/a)
delete-read-articles-on-quit (parameters: [yes/no]; default value: no)
dialogs-title-format (parameters: <format>; default value: "%N %V - Dialogs" (localized))
dirbrowser-title-format (parameters: <format>; default value: "%N %V - %?O?Open Directory&Save File? - %f" (localized))
display-article-progress (parameters: [yes/no]; default value: yes)
download-full-page (parameters: [yes/no]; default value: no)
download-retries (parameters: <number>; default value: 1)
download-timeout (parameters: <number>; default value: 30)
error-log (parameters: <path>; default value: "")
external-url-viewer (parameters: <command>; default value: "")
feed-sort-order (parameters: <sortfield>[-<direction>]; default value: none)
feedbin-flag-star (parameters: <flag>; default value: "")
feedbin-login (parameters: <login>; default value: "")
feedbin-password (parameters: <password>; default value: "")
feedbin-passwordeval (parameters: <command>; default value: "")
feedbin-passwordfile (parameters: <path>; default value: "")
feedbin-url (parameters: <url>; default value: "https://api.feedbin.com")
feedhq-flag-share (parameters: <flag>; default value: "")
feedhq-flag-star (parameters: <flag>; default value: "")
feedhq-login (parameters: <login>; default value: "")
feedhq-min-items (parameters: <number>; default value: 20)
feedhq-password (parameters: <password>; default value: "")
feedhq-passwordeval (parameters: <command>; default value: "")
feedhq-passwordfile (parameters: <path>; default value: "")
feedhq-show-special-feeds (parameters: [yes/no]; default value: yes)
feedhq-url (parameters: <url>; default value: "https://feedhq.org/")
feedlist-format (parameters: <format>; default value: "%4i %n %11u %t")
feedlist-title-format (parameters: <format>; default value: "%N %V - %?F?Feeds&Your feeds? (%u unread, %t total)%?F? matching filter '%F'&?%?T? - tag '%T'&?" (localized))
filebrowser-title-format (parameters: <format>; default value: "%N %V - %?O?Open File&Save File? - %f" (localized))
freshrss-flag-star (parameters: <flag>; default value: "")
freshrss-login (parameters: <login>; default value: "")
freshrss-min-items (parameters: <number>; default value: 20)
freshrss-password (parameters: <password>; default value: "")
freshrss-passwordeval (parameters: <command>; default value: "")
freshrss-passwordfile (parameters: <path>; default value: "")
freshrss-show-special-feeds (parameters: [yes/no]; default value: yes)
freshrss-url (parameters: <url>; default value: "")
goto-first-unread (parameters: [yes/no]; default value: yes)
goto-next-feed (parameters: [yes/no]; default value: yes)
help-title-format (parameters: <format>; default value: "%N %V - Help" (localized))
highlight (parameters: <target> <regex> <fgcolor> [<bgcolor> [<attribute> ...]]; default value: n/a)
highlight-article (parameters: <filterexpr> <fgcolor> <bgcolor> [<attribute> ...]; default value: n/a)
highlight-feed (parameters: <filterexpr> <fgcolor> <bgcolor> [<attribute> ...]; default value: n/a)
history-limit (parameters: <number>; default value: 100)
html-renderer (parameters: <command>; default value: internal)
http-auth-method (parameters: <method>; default value: any)
ignore-article (parameters: <feed> <filterexpr>; default value: n/a)
ignore-mode (parameters: [download/display]; default value: download)
include (parameters: <path>; default value: n/a)
inoreader-app-id (parameters: <string>; default value: "")
inoreader-app-key (parameters: <string>; default value: "")
inoreader-flag-share (parameters: <flag>; default value: "")
inoreader-flag-star (parameters: <flag>; default value: "")
inoreader-login (parameters: <login>; default value: "")
inoreader-min-items (parameters: <number>; default value: 20)
inoreader-password (parameters: <password>; default value: "")
inoreader-passwordeval (parameters: <command>; default value: "")
inoreader-passwordfile (parameters: <path>; default value: "")
inoreader-show-special-feeds (parameters: [yes/no]; default value: yes)
itemview-title-format (parameters: <format>; default value: "%N %V - Article '%T' (%u unread, %t total)" (localized))
keep-articles-days (parameters: <number>; default value: 0)
macro (parameters: <macro key> <command list> [-- "<macro description>"]; default value: n/a)
mark-as-read-on-hover (parameters: [yes/no]; default value: no)
max-browser-tabs (parameters: <number>; default value: 10)
max-download-speed (parameters: <number>; default value: 0)
max-items (parameters: <number>; default value: 0)
miniflux-flag-star (parameters: <flag>; default value: "")
miniflux-login (parameters: <username>; default value: "")
miniflux-min-items (parameters: <number>; default value: 100)
miniflux-password (parameters: <password>; default value: "")
miniflux-passwordeval (parameters: <command>; default value: "")
miniflux-passwordfile (parameters: <path>; default value: "")
miniflux-show-special-feeds (parameters: [yes/no]; default value: yes)
miniflux-token (parameters: <API Token>; default value: "")
miniflux-tokeneval (parameters: <command>; default value: "")
miniflux-tokenfile (parameters: <API Token>; default value: "")
miniflux-url (parameters: <url>; default value: "")
newsblur-login (parameters: <login>; default value: "")
newsblur-min-items (parameters: <number>; default value: 20)
newsblur-password (parameters: <password>; default value: "")
newsblur-passwordeval (parameters: <command>; default value: "")
newsblur-passwordfile (parameters: <path>; default value: "")
newsblur-url (parameters: <url>; default value: "https://newsblur.com")
notify-always (parameters: [yes/no]; default value: no)
notify-beep (parameters: [yes/no]; default value: no)
notify-format (parameters: <string>; default value: "Newsboat: finished reload, %f unread feeds (%n unread articles total)" (localized))
notify-program (parameters: <command>; default value: "")
notify-screen (parameters: [yes/no]; default value: no)
notify-xterm (parameters: [yes/no]; default value: no)
ocnews-flag-star (parameters: <character>; default value: "")
ocnews-login (parameters: <username>; default value: "")
ocnews-password (parameters: <password>; default value: "")
ocnews-passwordeval (parameters: <command>; default value: "")
ocnews-passwordfile (parameters: <path>; default value: "")
ocnews-url (parameters: <url>; default value: "")
oldreader-flag-share (parameters: <flag>; default value: "")
oldreader-flag-star (parameters: <flag>; default value: "")
oldreader-login (parameters: <login>; default value: "")
oldreader-min-items (parameters: <number>; default value: 20)
oldreader-password (parameters: <password>; default value: "")
oldreader-passwordeval (parameters: <command>; default value: "")
oldreader-passwordfile (parameters: <path>; default value: "")
oldreader-show-special-feeds (parameters: [yes/no]; default value: yes)
openbrowser-and-mark-jumps-to-next-unread (parameters: [yes/no]; default value: no)
opml-url (parameters: <url> ...; default value: "")
pager (parameters: [<command>/internal]; default value: internal)
podcast-auto-enqueue (parameters: [yes/no]; default value: no)
prepopulate-query-feeds (parameters: [yes/no]; default value: no)
proxy (parameters: <server:port>; default value: n/a)
proxy-auth (parameters: <auth>; default value: n/a)
proxy-auth-method (parameters: <method>; default value: any)
proxy-type (parameters: <type>; default value: http)
refresh-on-startup (parameters: [yes/no]; default value: no)
reload-only-visible-feeds (parameters: [yes/no]; default value: no)
reload-threads (parameters: <number>; default value: 1)
reload-time (parameters: <number>; default value: 60)
reset-unread-on-update (parameters: <url> [<url>...]; default value: n/a)
restrict-filename (parameters: [yes/no]; default value: yes)
run-on-startup (parameters: <list of operations>; default value: n/a)
save-path (parameters: <path-to-directory>; default value: ~/)
scrolloff (parameters: <number>; default value: 0)
search-highlight-colors (parameters: <fgcolor> <bgcolor> [<attribute> ...]; default value: black yellow bold)
searchresult-title-format (parameters: <format>; default value: "%N %V - Search results for '%s' (%u unread, %t total)%?F? matching filter '%F'&?" (localized))
selectfilter-title-format (parameters: <format>; default value: "%N %V - Select Filter" (localized))
selecttag-format (parameters: <format>; default value: "%4i %T (%u)")
selecttag-title-format (parameters: <format>; default value: "%N %V - Select Tag" (localized))
show-keymap-hint (parameters: [yes/no]; default value: yes)
show-read-articles (parameters: [yes/no]; default value: yes)
show-read-feeds (parameters: [yes/no]; default value: yes)
show-title-bar (parameters: [yes/no]; default value: yes)
ssl-verifyhost (parameters: [yes/no]; default value: yes)
ssl-verifypeer (parameters: [yes/no]; default value: yes)
suppress-first-reload (parameters: [yes/no]; default value: no)
swap-title-and-hints (parameters: [yes/no]; default value: no)
text-width (parameters: <number>; default value: 0)
toggleitemread-jumps-to-next-unread (parameters: [yes/no]; default value: no)
ttrss-flag-publish (parameters: <character>; default value: "")
ttrss-flag-star (parameters: <character>; default value: "")
ttrss-login (parameters: <username>; default value: "")
ttrss-mode (parameters: [multi/single]; default value: multi)
ttrss-password (parameters: <password>; default value: "")
ttrss-passwordeval (parameters: <command>; default value: "")
ttrss-passwordfile (parameters: <path>; default value: "")
ttrss-url (parameters: <url>; default value: "")
unbind-key (parameters: <key> [<dialog>]; default value: n/a)
urls-source (parameters: <source>; default value: "local")
urlview-title-format (parameters: <format>; default value: "%N %V - URLs" (localized))
use-proxy (parameters: [yes/no]; default value: no)
user-agent (parameters: <string>; default value: "")
wrap-scroll (parameters: [yes/no]; default value: no)
AVAILABLE OPERATIONS¶
open (default key: ENTER)
quit (default key: Q)
hard-quit (default key: Shift + Q)
reload (default key: R)
reload-all (default key: Shift + R)
mark-feed-read (default key: Shift + A)
mark-all-feeds-read (default key: Shift + C)
mark-all-above-as-read (default key: n/a)
save (default key: S)
save-all (default key: n/a)
next-unread (default key: N)
prev-unread (default key: P)
next (default key: Shift + J)
prev (default key: Shift + K)
random-unread (default key: Ctrl + K)
open-in-browser (default key: O)
open-in-browser-noninteractively (default key: n/a)
open-in-browser-and-mark-read (default key: Shift + O)
open-all-unread-in-browser (default key: n/a)
open-all-unread-in-browser-and-mark-read (default key: n/a)
help (default key: ?)
toggle-source-view (default key: Ctrl + U)
toggle-article-read (default key: Shift + N)
toggle-show-read-feeds (default key: L)
show-urls (default key: U)
clear-tag (default key: Ctrl + T)
set-tag (default key: T)
open-search (default key: /)
goto-url (default key: #)
one (default key: 1)
two (default key: 2)
three (default key: 3)
four (default key: 4)
five (default key: 5)
six (default key: 6)
seven (default key: 7)
eight (default key: 8)
nine (default key: 9)
zero (default key: 0)
cmd-one (default key: 1)
cmd-two (default key: 2)
cmd-three (default key: 3)
cmd-four (default key: 4)
cmd-five (default key: 5)
cmd-six (default key: 6)
cmd-seven (default key: 7)
cmd-eight (default key: 8)
cmd-nine (default key: 9)
enqueue (default key: E)
edit-urls (default key: Shift + E)
reload-urls (default key: Ctrl + R)
redraw (default key: Ctrl + L)
cmdline (default key: :)
set-filter (default key: Shift + F)
select-filter (default key: F)
clear-filter (default key: Ctrl + F)
bookmark (default key: Ctrl + B)
edit-flags (default key: Ctrl + E)
next-unread-feed (default key: Ctrl + N)
prev-unread-feed (default key: Ctrl + P)
next-feed (default key: J)
prev-feed (default key: K)
delete-article (default key: Shift + D)
delete-all-articles (default key: Ctrl + D)
purge-deleted (default key: $)
view-dialogs (default key: V)
close-dialog (default key: Ctrl + X)
next-dialog (default key: Ctrl + V)
prev-dialog (default key: Ctrl + G)
pipe-to (default key: |)
sort (default key: G)
rev-sort (default key: Shift + G)
up (default key: UP)
down (default key: DOWN)
pageup (default key: PPAGE)
pagedown (default key: NPAGE)
halfpageup (default key: n/a)
halfpagedown (default key: n/a)
home (default key: HOME)
end (default key: END)
macro-prefix (default key: ,)
switch-focus (default key: TAB)
goto-title (default key: n/a)
prevsearchresults (default key: Z)
article-feed (default key: n/a)
TAGGING¶
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:
https://blog.fefe.de/rss.xml?html interesting conspiracy news "cool stuff" https://rss.orf.at/news.xml news orf https://www.heise.de/newsticker/heise.rdf news interesting
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 Ctrl + 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:
https://rss.orf.at/news.xml "~ORF News"
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.
https://rss.orf.at/news.xml ! news http://feeds.bbci.co.uk/news/world/rss.xml ! news "query:News from around the globe:tags # \"news\""
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.
SCRIPTS AND FILTERS¶
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:
exec:~/bin/execurl-script filter:~/bin/filter-script:https://some.test/url
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):
"exec:~/bin/execurl-script param1 param2"
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:
"filter:~/bin/filter-script param1 param2:https://url/foobar"
In both cases, the tagging feature as described above is still available:
exec:~/bin/execurl-script tag1 tag2 "quoted tag" filter:~/bin/filter-script:https://some.test/url tag3 tag4 tag5
If you need to write your own extension, see this <https://web.archive.org/web/20090724045314/http://kiza.kcore.de/software/snownews/snowscripts/writing> short guide" for an introduction. A collection of existing scripts <https://github.com/msharov/snownews/tree/de3bd8b28191c4d4bc1be18275786613bcbc0c94/docs/untested> and filters <https://github.com/msharov/snownews/tree/9fb45e4cdf1cf9dea55b9af66c13a4c238809851/docs/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.
COMMAND LINE¶
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
q
save <filename>
set <variable>[=<value>|&|!]
tag <tagname>
goto <case-insensitive substring>
source <filename> [...]
dumpconfig <filename>
<number>
FILES¶
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 <https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>, 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:
config, urls
cache.db, history.search, history.cmdline, queue
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:
dotdir | XDG | |
Newsboat | ~/.newsboat/cache.db.lock | $XDG_DATA_HOME/newsboat/cache.db.lock |
Podboat | ~/.newsboat/pb-lock.pid | $XDG_DATA_HOME/newsboat/.lock |
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’s lock can be placed elsewhere using —lock-file command-line argument.
dotfiles
~/.newsboat/urls
XDG
$XDG_CONFIG_HOME/newsboat/urls
Note: if the XDG_CONFIG_HOME environment variable is not set, Newsboat behaves as if it was set to ~/.config.
ENVIRONMENT¶
BROWSER
CURL_CA_BUNDLE
This option is useful if your libcurl is built without useful certificate information, and you can’t rebuild the library yourself.
EDITOR
NO_PROXY
This variable contains a comma-separated list of hostnames, domain names, and IP addresses.
Domain names match subdomains, i.e. "example.com" also matches "foo.example.com". Domain names that start with a dot only match subdomains, e.g. ".example.com" matches "bar.example.com" but not "example.com" itself.
IPv6 addresses are written without square brackets, and are matched as strings. Thus "::1" doesn’t match "::0:1" even though this is the same address.
PAGER
TMPDIR
VISUAL
XDG_CONFIG_HOME
XDG_DATA_HOME
SEE ALSO¶
AUTHOR¶
Alexander Batischev
2024-09-24 |