FreeBSD Manual Pages
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 config- file] [-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 arti- cles, 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 ma- cOS. OPTIONS -h, --help Display help -r, --refresh-on-start Refresh feeds on start -e, --export-to-opml Export feeds as OPML to stdout. This currently outputs OPML 1.0, losing all tag information, but this is subject to change to 2.0 in the fu- ture. --export-to-opml2 Export feeds as OPML 2.0, including tags, to stdout -X, --vacuum Compact the cache by: 1) reclaiming the space that was left empty when data was deleted; and 2) defragmenting the entries in the cache. This doesn't delete the entries; for that, see cleanup-on-quit, delete-read-articles-on-quit, keep-articles-days, and max-items set- tings. --cleanup Remove unreferenced entries from the cache and quit Newsboat. Feeds and their articles will be removed if the feedurl is no longer in the urls file. 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 Get version information about Newsboat and the libraries it uses -i opmlfile, --import-from-opml=opmlfile Import an OPML file -u urlfile, --url-file=urlfile Use an alternative URL file -c cachefile, --cache-file=cachefile Use an alternative cache file -C configfile, --config-file=configfile Use an alternative configuration file --queue-file=queuefile Use an alternative queue file --search-history-file=searchhistoryfile Use an alternative search history file --cmdline-history-file=cmdlinehistoryfile Use an alternative command line history file -x command ..., --execute=command... Execute one or more commands to run Newsboat unattended. Currently available commands are reload and print-unread. -l loglevel, --log-level=loglevel Generate a logfile with a certain loglevel (valid values: 1 to 6, for user error, critical, error, warning, info, and debug respectively). Filename can be specified using the --log-file option. If not speci- fied, a filename is generated of the form newsboat_<date-time>.log -d logfile, --log-file=logfile Use this logfile as output when logging debug messages. Please note that this only works when providing a loglevel. -E file, --export-to-file=file Export a list of read articles (resp. their GUIDs). This can be used to transfer information about read articles between different computers. -I file, --import-from-file=file Import a list of read articles and mark them as read if they are held in the cache. This is to be used in conjunction with the -E commandline parameter. FIRST STEPS After you've installed Newsboat, you can run it for the first time by typ- ing newsboat on your command prompt. This will bring you the following mes- sage: 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 user- name/password: https://username:password@hostname.domain.tld/feed.rss 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 ac- cess 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 in- terface. 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: file:///var/log/rss_eventlog.xml 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 a or pressing Shift + Q from anywhere a 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: * Press Shift + R to download articles for all feeds. * Press R to download articles for the selected feed. * Press / to search all articles in all feeds. * Press Enter to go to the article list of a selected feed. * Press Q to close Newsboat. 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 num- ber 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 download- ing. 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 down- loads 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: * Press Q to go back to the Feed List View. * Press / to search all articles of this feed. * Press Enter to read a selected article. 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: * Press any number to open an article link in the browser. For numbers larger than 9 type #, then the number and press Enter. * Press O to open the article in the browser. * Press Q to go back to the Article List View. 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 com- plete 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 gen- eral: <config-command> <arg1> ... The configuration file can contain comments, which start with the # charac- ter 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 ^R feedlist 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 new- line. It doesn't do anything else at all. For example, this nicely format- ted 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 quotingA a 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 argu- ments. 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 back- slash: 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 com- mand, 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 configura- tion. Key Bindings New style key bindings described here are supported since Newsboat 2.39. You can bind a key (or sequence of keys) to an operation (or a list of op- erations) with the bind configuration command. The syntax for a binding looks like this: bind <key-sequence> <dialog>[,<dialog>] <operation-list> [-- "<description>"] Warning: Limitations Bindings that share a prefix must all have the same length; otherwise, only the last binding is created. For example: bind ab everywhere a| bind abc everywhere a| will only create a binding for abc. Re-ordering the commands will cre- ate a binding for ab. This avoids ambiguity when ab is typed and Newsboat doesn't know if it should run the binding for ab already or the user is going to press c next, triggering the other binding. To have both bindings, either: * rename them to have different prefixes (e.g. ab and bcd), or * make them the same length (e.g. rename ab to abd to match the length of abc). Key Sequence Lowercase keys, uppercase keys and special characters are written liter- ally. Key combinations with Ctrl are written using the caret ^. For instance Ctrl + R equals to ^R. Please be aware that all Ctrl-related key combina- tions need to be written in uppercase. Alternatively, key combinations using Shift or Ctrl can be written like <S-a> and <C-a>, for Shift + A and Ctrl + A respectively. Note that this alternative syntax only works with the bind command. It is not supported with the older bind-key command. The following identifiers for special keys are supported: * <ENTER> (Enter key) * <BACKSPACE> (backspace key) * <LEFT> (left cursor) * <RIGHT> (right cursor) * <UP> (up cursor) * <DOWN> (down cursor) * <PPAGE> (page up cursor) * <NPAGE> (page down cursor) * <HOME> (cursor to beginning of list/article) * <END> (cursor to end of list/article) * <ESC> (Esc key) * <TAB> (Tab key) * <LT> (< key) * <GT> (> key) * <^> (^ key, can also be specified as just ^ if it is not followed by a letter) * <F1> to <F12> (F1 key to F12 key) Multiple keys can be placed in sequence. For example gg means pressing g twice and ^O<ENTER> means pressing Ctrl + O followed by Enter. Pressing Esc will cancel a multi-key input. Dialog A dialog is a context in which the key binding is active. Available dialogs are: * everywhere * feedlist * filebrowser * help * articlelist * article * tagselection * filterselection * urlview * podboat * dirbrowser * searchresultslist Multiple dialogs can be specified with a comma in between. For example: bind k feedlist,articlelist,urlview up bind j feedlist,articlelist,urlview down or using everywhere to apply the binding in all dialogs: bind k everywhere up bind j everywhere down Operation List Operations get executed when pressing the corresponding sequence of keys. For a complete list of available operations see [_newsboat_operations] and [_podboat_operations]. Multiple operations can be specified by writing them down separated by a semicolon. Some operations allow specifying an argument, e.g. set <config option> <config value> can be used to change a configuration option. A sequence with two dashes followed by text between double quotes can be used to add a description to a binding (e.g. -- "some description"). If present, the description is shown in the help dialog. In combination, this might look like: bind of everywhere set browser "firefox" ; open-in-browser -- "Open in Firefox" The above example means that pressing o followed by f will change the con- figured browser to firefox and then run the open-in-browser command to open the feed/article in the configured browser. bind is similar to macros but is more flexible. Macros are configured glob- ally, whereas bind can be applied to specific dialogs. Additionally, macros always require pressing 2 keys (macro-prefix followed by a key specific to the macro) while bind can specify a key-sequence of any length. Old Style Key Bindings You can bind a single key to a single operation with the bind-key configu- ration command. This is an older, more limited form of keybinding syntax. You can specify an optional dialog. This is the context in which the key binding is active. The syntax for an old style key binding looks like this: bind-key <key> <operation> [<dialog>] Key Lowercase keys, uppercase keys and special characters are written liter- ally. Key combinations with Ctrl are written using the caret ^. For instance Ctrl + R equals to ^R. Please be aware that all Ctrl-related key combina- tions need to be written in uppercase. The following identifiers for special keys are supported: * ENTER (Enter key) * BACKSPACE (backspace key) * LEFT (left cursor) * RIGHT (right cursor) * UP (up cursor) * DOWN (down cursor) * PPAGE (page up cursor) * NPAGE (page down cursor) * HOME (cursor to beginning of list/article) * END (cursor to end of list/article) * ESC (Esc key) * TAB (Tab key) * F1 to F12 (F1 key to F12 key) Operation An operation gets executed when pressing the corresponding key. For a com- plete list of available operations see [_newsboat_operations] and [_pod- boat_operations]. Dialog A dialog is a context in which the key binding is active. Available dialogs are: * all (default if not specified) * feedlist * filebrowser * help * articlelist * article * tagselection * filterselection * urlview * podboat * dirbrowser * searchresultslist 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 follow- ing colors are supported: * black * red * green * yellow * blue * magenta * cyan * white * default * color<n>, e.g. color123 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 attrib- utes are supported: * standout * underline * reverse * blink * dim * bold * protect * invis Currently, the following elements are supported: * background: the application background * listnormal: a normal list item * listfocus: the currently selected list item * listnormal_unread: an unread list item * listfocus_unread: the currently selected unread list item * title (added in 2.25): current dialog's title, which is usually at the top of the screen (but see show-title-bar and swap-title-and-hints). If you don't specify a style for this element, then the info style is used * info: the hints bar, which is usually at the bottom of the screen (but see show-keymap-hint and swap-title-and-hints) * hint-key (added in 2.25): a key in the hints bar. If you don't specify a style for this element, then the info style is used * hint-keys-delimiter (added in 2.25): the comma that separates keys in the hints bar. If you don't specify a style for this element, then the info style is used * hint-separator (added in 2.25): the colon separating keys from their descriptions in the hints bar. If you don't specify a style for this element, then the info style is used * hint-description (added in 2.25): a description of a key in the hints bar. If you don't specify a style for this element, then the info style is used * article: the article text * end-of-text-marker: filler lines (~) below blocks of text 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) If set to yes, then the description will always be displayed even if e.g. a <content:encoded> tag has been found. (example: always-dis- play-description yes) always-download (parameters: <url> [<url>...]; default value: n/a) Specifies one or more feed URLs that should always be downloaded, re- gardless of their Last-Modified timestamp and ETag header. This option can be specified multiple times. (example: always-download "https://www.n-tv.de/23.rss") article-sort-order (parameters: <sortfield>[-<direction>]; default value: date-asc) The <sortfield> specifies which article property shall be used for sorting. Currently available are: date, title, flags, author, link, guid, and random. The optional <direction> can be either asc for as- cending order, or desc for descending order. Note that direction does not affect the random sorting. For date, desc order is the default, i.e. date is the same as date-desc; for all others, asc is the default. Also, the directions for date are reversed: desc means the newest items are first, whereas asc means the oldest items are first. These incon- sistencies will be fixed in a future major version of Newsboat. (exam- ple: article-sort-order author-desc) articlelist-format (parameters: <format>; default value: "%4i %f %D %6L %?T?|%-17T| ?%t") This variable defines the format of entries in the article list. See the FORMAT STRINGS section in the documentation for more information. (example: articlelist-format "%4i %f %D %?T?|%-17T| ?%t") articlelist-title-format (parameters: <format>; default value: "%N %V - Ar- ticles in feed '%T' (%u unread, %t total)%?F? matching filter '%F'&? - %U" (localized)) Format of the title in article list. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: arti- clelist-title-format "Articles in feed '%T' (%u unread)") auto-reload (parameters: [yes/no]; default value: no) If set to yes, all feeds will be automatically reloaded at start up and then continuously after a certain time has passed (see reload-time). See also refresh-on-startup to only reload the feeds at start up, but not continuously. Enabling suppress-first-reload omits the reload on start up. (example: auto-reload yes) bind (parameters: <key-sequence> <dialog>[,<dialog>] <command-list> [-- "<binding description>"]; default value: n/a) Bind sequence of keys <key-sequence> to <command-list>. This means that whenever the keys in <key-sequence> are pressed in order, then the list of commands in <command-list> is executed (if applicable in the current dialog). For more information see Key Bindings. Optionally, a descrip- tion can be added. If present, the description is shown in the help form. See also unbind-key to remove a key binding. (example: bind of everywhere set browser "firefox" ; open-in-browser) bind-key (parameters: <key> <operation> [<dialog>]; default value: n/a) Bind key <key> to <operation>. This means that whenever <key> is pressed, then <operation> is executed (if applicable in the current di- alog). For more information see Old Style Key Bindings. See also un- bind-key to remove a key binding. (example: bind-key ^R reload-all) bookmark-autopilot (parameters: [yes/no]; default value: no) If set to yes, the configured bookmark command is executed without any further input asked from user, unless the url or the title cannot be found/guessed. (example: bookmark-autopilot yes) bookmark-cmd (parameters: <command>; default value: "") If set, then <command> will be used as bookmarking plugin. See the doc- umentation on bookmarking for further information. (example: book- mark-cmd "~/bin/delicious-bookmark.sh") bookmark-interactive (parameters: [yes/no]; default value: no) If set to yes, then the configured bookmark command is an interactive program. (example: bookmark-interactive yes) browser (parameters: <command>; default value: %BROWSER, otherwise lynx) Set the browser command to use when opening an article in the browser. If the BROWSER environment variable is set, it will be used as the de- fault browser, otherwise lynx will be used. For more information, see Using Browser. (example: browser "w3m %u") cache-file (parameters: <path>; default value: "~/.newsboat/cache.db" or "~/.local/share/cache.db" (see the FILES section)) This configuration option sets the cache file. This is especially use- ful if the filesystem of your home directory doesn't support proper locking (e.g. NFS). (example: cache-file "/tmp/testcache.db") cleanup-on-quit (parameters: [yes/no/nudge]; default value: nudge) If set to yes, then the cache gets locked and superfluous feeds and items are removed, such as feeds that can't be found in the urls con- figuration file anymore. Run newsboat --cleanup to do this manually. If you encounter a warning about unreachable feeds having been found, you may see the feed urls listed by creating a log file via the error-log option. With nudge, newsboat will wait for user input if the warning is printed. (example: cleanup-on-quit yes) color (parameters: <element> <fgcolor> <bgcolor> [<attribute> ...]; default value: n/a) Set the foreground color, background color and optional attributes for a certain element. For available colors and attributes, see the Colors section. (example: color background white black) confirm-delete-all-articles (parameters: [yes/no]; default value: yes) If set to yes, then Newsboat will ask for confirmation whether the user wants to delete all articles. (example: confirm-delete-all-articles no) confirm-exit (parameters: [yes/no]; default value: no) If set to yes, then Newsboat will ask for confirmation whether the user really wants to quit Newsboat. (example: confirm-exit yes) confirm-mark-all-feeds-read (parameters: [yes/no]; default value: yes) If set to yes, then Newsboat will ask for confirmation whether the user wants to mark all feeds as read. (example: confirm-mark-all-feeds-read no) confirm-mark-feed-read (parameters: [yes/no]; default value: yes) If set to yes, then Newsboat will ask for confirmation on whether the user wants to mark a feed as read. (example: confirm-mark-feed-read no) cookie-cache (parameters: <path>; default value: "") Set a cookie cache. If set, cookies will be cached in (i.e. read from and written to) this file, using Netscape format <http://www.cookiecentral.com/faq/#3.5>. (example: cookie-cache "~/.newsboat/cookies.txt") datetime-format (parameters: <date/time format>; default value: %b %d) This format specifies the date/time format in the article list. For a detailed documentation on most of the allowed formats, consult the man- page of strftime(3). %L is a custom format not available in strftime which lists the days since the article was published (e.g. "2 days ago"). (example: datetime-format "%D, %R") define-filter (parameters: <name> <filterexpr>; default value: n/a) With this command, you can predefine filters, which you can later se- lect from a list, and which are then applied after selection. This is especially useful for filters that you need often and you don't want to enter them every time you need them. (example: define-filter "all feeds with 'fun' tag" "tags # \"fun\"") delete-read-articles-on-quit (parameters: [yes/no]; default value: no) If set to yes, all read articles will be deleted when quiting Newsboat. This option only applies if cleanup-on-quit is set to yes or if the --cleanup argument is passed. (example: delete-read-articles-on-quit yes) dialogs-title-format (parameters: <format>; default value: "%N %V - Di- alogs" (localized)) Format of the title in dialog list. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: di- alogs-title-format "%N %V - Dialogs") dirbrowser-title-format (parameters: <format>; default value: "%N %V - %?O?Open Directory&Save File? - %f" (localized)) Format of the title in directory browser. See the FORMAT STRINGS sec- tion of the Newsboat manual for details on available formats. (example: dirbrowser-file-format "%?O?Open Directory&Save File? - %f") display-article-progress (parameters: [yes/no]; default value: yes) If set to yes, then a read progress (in percent) is displayed in the article view. Otherwise, no read progress is displayed. (example: dis- play-article-progress no) download-full-page (parameters: [yes/no]; default value: no) If set to yes, then for all feed items with no content but with a link, the link is downloaded and the result used as content instead. This may significantly increase the download times of "empty" feeds. (example: download-full-page yes) download-retries (parameters: <number>; default value: 1) How many times Newsboat shall try to successfully download a feed be- fore giving up. This is an option to improve the success of downloads on slow and shaky connections such as via a TOR proxy. (example: down- load-retries 4) download-timeout (parameters: <number>; default value: 30) The number of seconds Newsboat shall wait when downloading a feed be- fore giving up. This is an option to improve the success of downloads on slow and shaky connections such as via a TOR proxy. (example: down- load-timeout 60) error-log (parameters: <path>; default value: "") If set, then user errors (e.g. errors regarding defunct RSS feeds) will be logged to this file. (example: error-log "~/.newsboat/error.log") external-url-viewer (parameters: <command>; default value: "") If set, then show-urls will pipe the current article to a specific ex- ternal tool instead of using the internal URL viewer. This can be used to integrate tools such as urlview. (example: external-url-viewer "urlview") feed-sort-order (parameters: <sortfield>[-<direction>]; default value: none) The <sortfield> specifies which feed property shall be used for sort- ing; currently available are: firsttag, title, articlecount, unreadar- ticlecount, lastupdated, latestunread and none. The optional <direc- tion> specifies the sort direction. asc specifies ascending sorting, desc specifies descending sorting. desc is the default. (example: feed-sort-order firsttag) feedbin-flag-star (parameters: <flag>; default value: "") If set and Feedbin support is used, then all articles that are flagged with the specified flag are being "starred" in Feedbin and appear in the list of "Starred items". (example: feedbin-flag-star "b") feedbin-login (parameters: <login>; default value: "") This variable sets your Feedbin login for Feedbin support. (example: feedbin-login "your-login") feedbin-password (parameters: <password>; default value: "") This variable sets your Feedbin password for Feedbin support. Double quotes and backslashes within it should be escaped. (example: feed- bin-password "here_goesAquote:\"") feedbin-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: feedbin-passwordeval "gpg --decrypt ~/.newsboat/feedbin-pass- word.gpg") feedbin-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: feedbin-passwordfile "~/.newsboat/feed- bin-pw.txt") feedbin-url (parameters: <url>; default value: "https://api.feedbin.com") Configures the URL where the Feedbin installation you want to use re- sides. (example: feedbin-url "https://example.com/feedbin/") feedhq-flag-share (parameters: <flag>; default value: "") If set and FeedHQ support is used, then all articles that are flagged with the specified flag are being "shared" in FeedHQ so that people that follow you can see it. (example: feedhq-flag-share "a") feedhq-flag-star (parameters: <flag>; default value: "") If set and FeedHQ support is used, then all articles that are flagged with the specified flag are being "starred" in FeedHQ and appear in the list of "Starred items". (example: feedhq-flag-star "b") feedhq-login (parameters: <login>; default value: "") This variable sets your FeedHQ login for FeedHQ support. (example: feedhq-login "your-login") feedhq-min-items (parameters: <number>; default value: 20) This variable sets the number of articles that are loaded from FeedHQ per feed. (example: feedhq-min-items 100) feedhq-password (parameters: <password>; default value: "") This variable sets your FeedHQ password for FeedHQ support. Double quotes and backslashes within it should be escaped. (example: feedhq-password "here_goesAquote:\"") feedhq-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: feedhq-passwordeval "gpg --decrypt ~/.newsboat/feedhq-pass- word.gpg") feedhq-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: feedhq-passwordfile "~/.newsboat/feedhq-pw.txt") feedhq-show-special-feeds (parameters: [yes/no]; default value: yes) If set and FeedHQ support is used, then "special feeds" like "People you follow" (articles shared by people you follow), "Starred items" (your starred articles) and "Shared items" (your shared articles) ap- pear in your subscription list. (example: feedhq-show-special-feeds "no") feedhq-url (parameters: <url>; default value: "https://feedhq.org/") Configures the URL where your FeedHQ instance resides. (example: feedhq-url "https://feedhq.example.com/") feedlist-format (parameters: <format>; default value: "%4i %n %11u %t") This variable defines the format of entries in the feed list. See the FORMAT STRINGS section in the documentation for more information. (ex- ample: feedlist-format " %n %4i - %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)) Format of the title in feed list. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: feedlist-title-format "Feeds (%u unread, %t total)") filebrowser-title-format (parameters: <format>; default value: "%N %V - %?O?Open File&Save File? - %f" (localized)) Format of the title in file browser. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: file- browser-title-format "%?O?Open File&Save File? - %f") freshrss-flag-star (parameters: <flag>; default value: "") If set and FreshRSS support is used, then all articles that are flagged with the specified flag are being "starred" in FreshRSS and appear in the list of "Starred items". (example: freshrss-flag-star "b") freshrss-login (parameters: <login>; default value: "") This variable sets your FreshRSS login for FreshRSS support. (example: freshrss-login "your-login") freshrss-min-items (parameters: <number>; default value: 20) This variable sets the number of articles that are loaded from FreshRSS per feed. (example: freshrss-min-items 100) freshrss-password (parameters: <password>; default value: "") This variable sets your FreshRSS password for FreshRSS support. Double quotes and backslashes within it should be escaped. (example: freshrss-password "here_goesAquote:\"") freshrss-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: freshrss-passwordeval "gpg --decrypt ~/.news- boat/freshrss-password.gpg") freshrss-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: freshrss-passwordfile "~/.news- boat/freshrss-pw.txt") freshrss-show-special-feeds (parameters: [yes/no]; default value: yes) If set and FreshRSS support is used, then a "Starred items" feed (con- taining your starred/favourited articles) appears in your subscription list. (example: freshrss-show-special-feeds "no") freshrss-url (parameters: <url>; default value: "") Configures the URL for the Google Reader API endpoint of your FreshRSS instance. (example: freshrss-url "https://freshrss.exam- ple.com/api/greader.php") goto-first-unread (parameters: [yes/no]; default value: yes) If set to yes, then the first unread article will be selected whenever a feed is entered. (example: goto-first-unread no) goto-next-feed (parameters: [yes/no]; default value: yes) If set to yes, then the next-unread, prev-unread and random-unread keys will search in other feeds for unread articles if all articles in the current feed are read. If set to no, then these keys will stop in the current feed. (example: goto-next-feed no) help-title-format (parameters: <format>; default value: "%N %V - Help" (lo- calized)) Format of the title in help window. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: help-title-format "%N %V - Help") highlight (parameters: <target> <regex> <fgcolor> [<bgcolor> [<attribute> ...]]; default value: n/a) With this command, you can highlight text parts in the feed list, the article list and the article view. For available colors and attributes, see the Colors section. (example: highlight all "newsboat" red) highlight-article (parameters: <filterexpr> <fgcolor> <bgcolor> [<at- tribute> ...]; default value: n/a) With this command, you can highlight articles in the article list if they match a filter expression. For available colors and attributes, see the Colors section. (example: highlight-article "author =~ \"An- dreas Krennmair\"" white red bold) highlight-feed (parameters: <filterexpr> <fgcolor> <bgcolor> [<attribute> ...]; default value: n/a) With this command, you can highlight feeds in the feed list if they match a filter expression. For available colors and attributes, see the Colors section. (example: highlight-feed unread > 100 white red bold) history-limit (parameters: <number>; default value: 100) Defines the maximum number of entries of commandline resp. search his- tory to be saved. To disable history saving, set it to 0. (example: history-limit 0) html-renderer (parameters: <command>; default value: internal) If set to internal, then the internal HTML renderer will be used. Oth- erwise, the specified command will be executed, the HTML to be rendered will be written to the command's stdin, and the program's output will be displayed. This makes it possible to use other, external programs, such as w3m, links or lynx, to render HTML. (example: html-renderer "w3m -dump -T text/html") http-auth-method (parameters: <method>; default value: any) Set HTTP authentication method. Allowed values: any, basic, digest, di- gest_ie (only available with libcurl 7.19.3 and newer), gssnegotiate, ntlm and anysafe. (example: http-auth-method digest) ignore-article (parameters: <feed> <filterexpr>; default value: n/a) If a downloaded article from <feed> matches <filterexpr>, then it is ignored and not presented to the user. This command is further ex- plained in the KILLFILES section below. (example: ignore-article "*" "title =~ \"Windows\"") ignore-mode (parameters: [download/display]; default value: download) This configuration option defines in what way an article is ignored (see ignore-article). If set to download, then it is ignored in the download/parsing phase and thus never written to the cache, if it set to display, it is ignored when displaying articles but is kept in the cache. (example: ignore-mode "display") include (parameters: <path>; default value: n/a) With this command, you can include other files to be interpreted as configuration files. This is especially useful to separate your config- uration into several files, e.g. key configuration, color configura- tion, ... (example: include "~/.newsboat/colors") inoreader-app-id (parameters: <string>; default value: "") Unique application ID issued by Inoreader. See "Inoreader" section. (example: inoreader-app-id "123456789") inoreader-app-key (parameters: <string>; default value: "") Application key issued by Inoreader. See "Inoreader" section. (example: inoreader-app-key "TmV3c2JvYXQgcm9ja3MgOikK") inoreader-flag-share (parameters: <flag>; default value: "") If set and Inoreader support is used, then all articles that are flagged with the specified flag are being "shared" in Inoreader so that people that follow you can see it. (example: inoreader-flag-share "a") inoreader-flag-star (parameters: <flag>; default value: "") If set and Inoreader support is used, then all articles that are flagged with the specified flag are being "starred" in Inoreader and appear in the list of "Starred items". (example: inoreader-flag-star "b") inoreader-login (parameters: <login>; default value: "") This variable sets your Inoreader login for Inoreader support. (exam- ple: inoreader-login "your-login") inoreader-min-items (parameters: <number>; default value: 20) This variable sets the number of articles that are loaded from Inore- ader per feed. (example: inoreader-min-items 100) inoreader-password (parameters: <password>; default value: "") This variable sets your Inoreader password for Inoreader support. Dou- ble quotes and backslashes within it should be escaped. (example: in- oreader-password "here_goesAquote:\"") inoreader-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: inoreader-passwordeval "gpg --decrypt ~/.newsboat/inore- ader-password.gpg") inoreader-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: inoreader-passwordfile "~/.newsboat/inore- ader-pw.txt") inoreader-show-special-feeds (parameters: [yes/no]; default value: yes) If set and Inoreader support is used, then "special feeds" like "Starred items" (your starred articles) and "Shared items" (your shared articles) appear in your subscription list. (example: inore- ader-show-special-feeds "no") itemview-title-format (parameters: <format>; default value: "%N %V - Arti- cle '%T' (%u unread, %t total)" (localized)) Format of the title in article view. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: itemview-title-format "Article '%T'") keep-articles-days (parameters: <number>; default value: 0) If set to a number greater than 0, only articles that were published within the last <number> days are kept, and older articles are deleted. If set to 0, this option is not active. Note that changing this setting won't bring back the articles that were deleted earlier; currently, there's no non-hacky way to bring back deleted articles. (example: keep-articles-days 30) macro (parameters: <macro key> <command list> [-- "<macro description>"]; default value: n/a) With this command, you can define a macro key and specify a list of commands that shall be executed when the macro prefix and the macro key are pressed. Optionally, a description can be added. If present, the description is shown in the help form. (example: macro k open; reload; quit -- "enter feed to reload it") mark-as-read-on-hover (parameters: [yes/no]; default value: no) If set to yes, then all articles that get selected in the article list are marked as read. (example: mark-as-read-on-hover yes) max-browser-tabs (parameters: <number>; default value: 10) Set the maximum number of articles to open in a browser when using the open-all-unread-in-browser or open-all-unread-in-browser-and-mark-read commands. (example: max-browser-tabs 4) max-download-speed (parameters: <number>; default value: 0) If set to a number greater than 0, the download speed per download is set to that limit (in KB/s). (example: max-download-speed 50) max-items (parameters: <number>; default value: 0) Set the maximum number of articles a feed can contain. When the thresh- old is crossed, old articles are dropped. If the number is set to 0, then all articles are kept. (example: max-items 100) miniflux-flag-save (parameters: <flag>; default value: "") If set and Miniflux support is used, then all articles that are flagged with the specified flag are being saved to external service configured on Miniflux instance. (example: miniflux-flag-save "b") miniflux-flag-star (parameters: <flag>; default value: "") If set and Miniflux support is used, then all articles that are flagged with the specified flag are being "starred" in Miniflux and appear in the list of "Starred items". (example: miniflux-flag-star "b") miniflux-login (parameters: <username>; default value: "") Sets the username for use with Miniflux. (example: miniflux-login "ad- min") miniflux-min-items (parameters: <number>; default value: 100) This variable sets the number of articles that are loaded from Miniflux per feed. (example: miniflux-min-items 20) miniflux-password (parameters: <password>; default value: "") Configures the password for use with Miniflux. Double quotes and back- slashes within it should be escaped. (example: miniflux-password "here_goesAquote:\"") miniflux-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: miniflux-passwordeval "gpg --decrypt ~/.newsboat/mini- flux-password.gpg") miniflux-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: miniflux-passwordfile "~/.newsboat/mini- flux-pw.txt") miniflux-show-special-feeds (parameters: [yes/no]; default value: yes) If set and Miniflux support is used, then a "Starred items" feed (con- taining your starred/favourited articles) appears in your subscription list. (example: miniflux-show-special-feeds "no") miniflux-token (parameters: <API Token>; default value: "") Sets the API Token for use with Miniflux. (example: miniflux-token "E-uTqU8r55KucuHz26tJbXfrZVRndwY_mZAsEfcC8Bg=") miniflux-tokeneval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your API token from an external command that is evaluated during login. This can be used to read your token from a gpg encrypted file or your system keyring. (example: miniflux-tokeneval "gpg --decrypt ~/.newsboat/mini- flux-token.gpg") miniflux-tokenfile (parameters: <API Token>; default value: "") Another alternative, by storing your plaintext token elsewhere in your system. (example: miniflux-tokenfile "~/.newsboat/miniflux-token.txt") miniflux-url (parameters: <url>; default value: "") Configures the URL where the Miniflux installation you want to use re- sides. (example: miniflux-url "https://example.com/miniflux/") newsblur-login (parameters: <login>; default value: "") This variable sets your NewsBlur login for NewsBlur support. (example: newsblur-login "your-login") newsblur-min-items (parameters: <number>; default value: 20) This variable sets the number of articles that are loaded from NewsBlur per feed. (example: newsblur-min-items 100) newsblur-password (parameters: <password>; default value: "") This variable sets your NewsBlur password for NewsBlur support. Double quotes and backslashes within it should be escaped. (example: news- blur-password "here_goesAquote:\"") newsblur-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: newsblur-passwordeval "gpg --decrypt ~/.newsboat/news- blur-password.gpg") newsblur-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: newsblur-passwordfile "~/.newsboat/news- blur-pw.txt") newsblur-url (parameters: <url>; default value: "https://newsblur.com") Configures the URL where the NewsBlur instance resides. (example: news- blur-url "https://localhost") notify-always (parameters: [yes/no]; default value: no) If set to no, notifications will only be made when there are new feeds or articles. If set to yes, notifications will be made regardless. (ex- ample: notify-always yes) notify-beep (parameters: [yes/no]; default value: no) If set to yes, then the speaker will beep on new articles. (example: notify-beep yes) notify-format (parameters: <string>; default value: "Newsboat: finished re- load, %f unread feeds (%n unread articles total)" (localized)) Format string that is used for formatting notifications. (example: no- tify-format "%d new articles (%n unread articles, %f unread feeds)") notify-program (parameters: <command>; default value: "") If set, then the configured program will be executed if new articles arrived (through a reload) or if notify-always is yes. The first para- meter of the called program contains the notification message. In order to pass other hard-coded arguments to the program, write an appropriate wrapper shell script and use it as <command> instead. (example: no- tify-program "~/bin/my-notifier") notify-screen (parameters: [yes/no]; default value: no) If set to yes, then a "privacy message" will be sent to the terminal, containing a notification message about new articles. This is espe- cially useful if you use terminal emulations such as GNU screen which implement privacy messages. (example: notify-screen yes) notify-xterm (parameters: [yes/no]; default value: no) If set to yes, then the xterm window title will be set to a notifica- tion message about new articles. (example: notify-xterm yes) ocnews-flag-star (parameters: <character>; default value: "") If set and ownCloud News support is used, then all articles that are flagged with the specified flag are being "starred" in ownCloud News. (example: ocnews-flag-star "s") ocnews-login (parameters: <username>; default value: "") Sets the username to use with the ownCloud instance. (example: oc- news-login "user") ocnews-password (parameters: <password>; default value: "") Configures the password to use with the ownCloud instance. Double quotes and backslashes within it should be escaped. (example: oc- news-password "here_goesAquote:\"") ocnews-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: ocnews-passwordeval "gpg --decrypt ~/.newsboat/ocnews-pass- word.gpg") ocnews-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: ocnews-passwordfile "~/.newsboat/ocnews-pw.txt") ocnews-url (parameters: <url>; default value: "") Configures the URL where the ownCloud instance resides. (example: oc- news-url "https://localhost/owncloud") oldreader-flag-share (parameters: <flag>; default value: "") If set and The Old Reader support is used, then all articles that are flagged with the specified flag are being "shared" in The Old Reader so that people that follow you can see it. (example: oldreader-flag-share "a") oldreader-flag-star (parameters: <flag>; default value: "") If set and The Old Reader support is used, then all articles that are flagged with the specified flag are being "starred" in The Old Reader and appear in the list of "Starred items". (example: ol- dreader-flag-star "b") oldreader-login (parameters: <login>; default value: "") This variable sets your The Old Reader login for The Older Reader sup- port. (example: oldreader-login "your-login") oldreader-min-items (parameters: <number>; default value: 20) This variable sets the number of articles that are loaded from The Old Reader per feed. (example: oldreader-min-items 100) oldreader-password (parameters: <password>; default value: "") This variable sets your The Old Reader password for The Old Reader sup- port. Double quotes and backslashes within it should be escaped. (exam- ple: oldreader-password "here_goesAquote:\"") oldreader-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: oldreader-passwordeval "gpg --decrypt ~/.newsboat/ol- dreader-password.gpg") oldreader-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: oldreader-passwordfile "~/.newsboat/ol- dreader-pw.txt") oldreader-show-special-feeds (parameters: [yes/no]; default value: yes) If set and The Old reader support is used, then "special feeds" like "People you follow" (articles shared by people you follow), "Starred items" (your starred articles) and "Shared items" (your shared arti- cles) appear in your subscription list. (example: oldreader-show-spe- cial-feeds "no") openbrowser-and-mark-jumps-to-next-unread (parameters: [yes/no]; default value: no) If set to yes, jump to the next unread item when an item is opened in the browser and marked as read. (example: open- browser-and-mark-jumps-to-next-unread yes) opml-url (parameters: <url> ...; default value: "") If the OPML online subscription mode is enabled, then the list of feeds will be taken from the OPML file found on this location. Optionally, you can specify more than one URL. All the listed OPML URLs will then be taken into account when loading the feed list. (example: opml-url "https://host.domain.tld/blogroll.opml" "https://example.com/anoth- eropmlfile.opml") pager (parameters: [<command>/internal]; default value: internal) If set to internal, then the internal pager will be used. Otherwise, the article to be displayed will be rendered to be a temporary file and then displayed with the configured pager. If the command is set to an empty string, the content of the PAGER environment variable will be used. If the command contains a placeholder %f, it will be replaced with the temporary filename. (example: pager "less %f") podcast-auto-enqueue (parameters: [yes/no]; default value: no) If set to yes, then all podcast URLs that are found in articles are added to the podcast download queue. See the PODCAST SUPPORT section in the documentation for more information. (example: podcast-auto-enqueue yes) prepopulate-query-feeds (parameters: [yes/no]; default value: no) If set to yes, then all query feeds are prepopulated with articles on startup. (example: prepopulate-query-feeds yes) proxy (parameters: <server:port>; default value: n/a) Set the proxy to use for downloading RSS feeds. (Don't forget to actu- ally enable the proxy with use-proxy yes.) Note that the NO_PROXY envi- ronment variable can disable the proxy for certain sites. (example: proxy localhost:3128) proxy-auth (parameters: <auth>; default value: n/a) Set the proxy authentication string. (example: proxy-auth user:pass- word) proxy-auth-method (parameters: <method>; default value: any) Set proxy authentication method. Allowed values: any, basic, digest, digest_ie (only available with libcurl 7.19.3 and newer), gssnegotiate, ntlm and anysafe. (example: proxy-auth-method ntlm) proxy-type (parameters: <type>; default value: http) Set proxy type. Allowed values: http, socks4, socks4a, socks5 and socks5h. (example: proxy-type socks5) refresh-on-startup (parameters: [yes/no]; default value: no) If set to yes, then all feeds will be reloaded when Newsboat starts up. This is equivalent to the -r commandline option. See also auto-reload to additionally reload the feeds continuously. (example: re- fresh-on-startup yes) reload-only-visible-feeds (parameters: [yes/no]; default value: no) If set to yes, then manually reloading all feeds will only reload the currently visible feeds, e.g. if a filter or a tag is set. (example: reload-only-visible-feeds yes) reload-threads (parameters: <number>; default value: 1) The number of parallel reload threads that shall be started when all feeds are reloaded. (example: reload-threads 3) reload-time (parameters: <number>; default value: 60) The number of minutes between automatic reloads. (example: reload-time 120) reset-unread-on-update (parameters: <url> [<url>...]; default value: n/a) Specifies one or more feed URLs for whose articles the unread flag will be reset if an article has been updated, i.e. its content has been changed. This is especially useful for RSS feeds where single articles are updated after publication, and you want to be notified of the up- dates. This option can be specified multiple times. (example: reset-un- read-on-update "https://blog.fefe.de/rss.xml?html") restrict-filename (parameters: [yes/no]; default value: yes) If set to no, Newsboat will not limit saved article filenames to ASCII characters. (example: restrict-filename no) run-on-startup (parameters: <list of operations>; default value: n/a) Specifies one or more Newsboat operations, separated by semicolons, which are executed on Newsboat startup. (example: run-on-startup next-unread; open; random-unread; open) save-path (parameters: <path-to-directory>; default value: ~/) The default path where articles shall be saved to. If an invalid path is specified, the current directory is used. (example: save-path "~/Saved Articles") scrolloff (parameters: <number>; default value: 0) Keep the configured number of lines above and below the selected item in lists. Configure a high number to keep the selected item in the cen- ter of the screen. (example: scrolloff 5) search-highlight-colors (parameters: <fgcolor> <bgcolor> [<attribute> ...]; default value: black yellow bold) This configuration command specifies the highlighting colors when searching for text from the article view. For available colors and at- tributes, see the Colors section. (example: search-highlight-colors white black bold) searchresult-title-format (parameters: <format>; default value: "%N %V - Search results for '%s' (%u unread, %t total)%?F? matching filter '%F'&?" (localized)) Format of the title in search result. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: searchresult-title-format "Search result") selectfilter-title-format (parameters: <format>; default value: "%N %V - Select Filter" (localized)) Format of the title in filter selection dialog. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (exam- ple: selectfilter-title-format "Select Filter") selecttag-format (parameters: <format>; default value: "%4i %T (%u)") Format of the lines in "Select tag" dialog. See the FORMAT STRINGS sec- tion in the documentation for more information. (example: select- tag-format "[%2i] %T (%n unread articles in %f feeds, %u feeds total)") selecttag-title-format (parameters: <format>; default value: "%N %V - Se- lect Tag" (localized)) Format of the title in tag selection dialog. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (exam- ple: selecttag-title-format "Select Tag") show-keymap-hint (parameters: [yes/no]; default value: yes) If set to no, then the keymap hints will not be displayed. (The keymap hints are usually at the bottom of the screen, but see swap-ti- tle-and-hints setting.) (example: show-keymap-hint no) show-read-articles (parameters: [yes/no]; default value: yes) If set to yes, then all articles of a feed are listed in the article list. If set to no, then only unread articles are listed. (example: show-read-articles no) show-read-feeds (parameters: [yes/no]; default value: yes) If set to yes, then all feeds, including those without unread articles, are listed. If set to no, then only feeds with one or more unread arti- cles are list. (example: show-read-feeds no) show-title-bar (parameters: [yes/no]; default value: yes) If set to no, then the title bar will not be displayed. (The title bar is usually at the top of the screen, but see swap-title-and-hints set- ting.) (example: show-title-bar no) ssl-verifyhost (parameters: [yes/no]; default value: yes) If set to no, skip verification of the certificate's name against host. (example: ssl-verifyhost no) ssl-verifypeer (parameters: [yes/no]; default value: yes) If set to no, skip verification of the peer's SSL certificate. (exam- ple: ssl-verifypeer no) suppress-first-reload (parameters: [yes/no]; default value: no) If set to yes, then the first automatic reload will be suppressed if auto-reload is set to yes. (example: suppress-first-reload yes) swap-title-and-hints (parameters: [yes/no]; default value: no) If set to yes, then the title (which is usually at the top of the screen) and the keymap hints (usually at the bottom) will exchange places. These bars can be hidden entirely, via the show-keymap-hint and show-title-bar settings. (example: swap-title-and-hints yes) text-width (parameters: <number>; default value: 0) If set to a number greater than 0, all HTML will be rendered to this maximum line length or the terminal width (whichever is smaller). If set to 0, the terminal width will always be used in the article view, while pipe-to, save, and save-all will wrap at 80 columns instead. Does not apply when using external renderer or viewing the source. Also note that "Link" header and "Links" section won't be affected by itathey contain URLs which are better not wrapped. (example: text-width 72) toggleitemread-jumps-to-next (parameters: [yes/no]; default value: yes) If set to yes, jump to the next item when an item's read status is tog- gled in the article list. If set to no, the cursor stays on the toggled item. (example: toggleitemread-jumps-to-next no) toggleitemread-jumps-to-next-unread (parameters: [yes/no]; default value: no) If set to yes, jump to the next unread item when an item's read status is toggled in the article list. If set to no, the behaviour is dictated by toggleitemread-jumps-to-next. (example: toggleitem- read-jumps-to-next-unread yes) ttrss-flag-publish (parameters: <character>; default value: "") If set and Tiny Tiny RSS support is used, then all articles that are flagged with the specified flag are being marked as "published" in Tiny Tiny RSS. (example: ttrss-flag-publish "b") ttrss-flag-star (parameters: <character>; default value: "") If set and Tiny Tiny RSS support is used, then all articles that are flagged with the specified flag are being "starred" in Tiny Tiny RSS. (example: ttrss-flag-star "a") ttrss-login (parameters: <username>; default value: "") Sets the username for use with Tiny Tiny RSS. (example: ttrss-login "admin") ttrss-mode (parameters: [multi/single]; default value: multi) Configures the mode in which Tiny Tiny RSS is used. In single-user mode, login and password are used for HTTP authentication, while in multi-user mode, they are used for authenticating with Tiny Tiny RSS. (example: ttrss-mode "single") ttrss-password (parameters: <password>; default value: "") Configures the password for use with Tiny Tiny RSS. Double quotes and backslashes within it should be escaped. (example: ttrss-password "here_goesAquote:\"") ttrss-passwordeval (parameters: <command>; default value: "") A more secure alternative to the above, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring. (example: ttrss-passwordeval "gpg --decrypt ~/.newsboat/ttrss-pass- word.gpg") ttrss-passwordfile (parameters: <path>; default value: "") Another alternative, by storing your plaintext password elsewhere in your system. (example: ttrss-passwordfile "~/.newsboat/ttrss-pw.txt") ttrss-url (parameters: <url>; default value: "") Configures the URL where the Tiny Tiny RSS installation you want to use resides. (example: ttrss-url "https://example.com/ttrss/") unbind-key (parameters: <key> [<dialog>]; default value: n/a) Unbind key <key>. This means that no operation is called when <key> is pressed. unbind-key uses the syntax for special keys as specified in the Key section of Old Style Key Bindings. If you provide "-a" as <key>, all currently bound keys will become unbound. Optionally, you can specify a dialog (for a list of available dialogs, see bind-key above). If you specify one, the key binding will only be unbound for the specified dialog. (example: unbind-key R) urls-source (parameters: <source>; default value: "local") This configuration command sets the source where URLs shall be re- trieved from. By default, this is the urls file. Alternatively, you can set it to opml, which enables Newsboat's OPML online subscription mode, to ttrss which enables Newsboat's Tiny Tiny RSS support, to oldreader, which enables Newsboat's The Old Reader support, to newsblur, which en- ables NewsBlur support, to feedbin for Feedbin support, to feedhq for FeedHQ support, to freshrss for FreshRSS support, to ocnews for own- Cloud News support, to inoreader for Inoreader support, or to miniflux for Miniflux support. Query feed specifications will be read from the local urls file regardless of this setting. (example: urls-source "ol- dreader") urlview-title-format (parameters: <format>; default value: "%N %V - URLs" (localized)) Format of the title in URL view. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: urlview-ti- tle-format "URLs") use-proxy (parameters: [yes/no]; default value: no) If set to yes, then the configured proxy will be used for downloading the RSS feeds. (example: use-proxy yes) user-agent (parameters: <string>; default value: "") If set to a non-zero-length string, this value will be used as HTTP User-Agent header for all HTTP requests. (example: user-agent "Lynx/2.8.5rel.1 libwww-FM/2.14") wrap-scroll (parameters: [yes/no]; default value: no) If set to yes, moving down while on the last item in a list will wrap around to the top and vice versa. (example: wrap-scroll yes) AVAILABLE OPERATIONS open (default key: ENTER) Open the currently selected feed or article. quit (default key: Q) Quit the program or return to the previous dialog (depending on the context). hard-quit (default key: Shift + Q) Quit the program without confirmation. reload (default key: R) Reload the currently selected feed. reload-all (default key: Shift + R) Reload all feeds. mark-feed-read (default key: Shift + A) Mark all articles in the currently selected feed read. mark-all-feeds-read (default key: Shift + C) Mark articles in all feeds read. mark-all-above-as-read (default key: n/a) Mark all above as read. save (default key: S) Export the currently selected article to a plain text file, word-wrapped according to the text-width setting. save-all (default key: n/a) Export all articles from the currently selected feed to plain text files, word-wrapped according to the text-width setting. next-unread (default key: N) Jump to the next unread article. prev-unread (default key: P) Jump to the previous unread article. next (default key: Shift + J) Jump to next list entry. prev (default key: Shift + K) Jump to previous list entry. random-unread (default key: Ctrl + K) Jump to a random unread article. open-in-browser (default key: O) Use browser to open the URL associated with the current article, feed, or entry in the URL view. open-in-browser-noninteractively (default key: n/a) Use browser to open the URL associated with the current article, feed, or entry in the URL view. This operation works similar to open-in-browser, but the output of the browser (stdout and stderr) is not shown, and the browser doesn't receive keyboard input. You would probably add & at the end of the browser command to put it into back- ground, too. open-in-browser-and-mark-read (default key: Shift + O) Use browser to open the URL associated with the current article, or en- try in the URL view. When used in the article list, it will also mark the article as read. open-all-unread-in-browser (default key: n/a) Open all the unread URLs in the current feed. open-all-unread-in-browser-and-mark-read (default key: n/a) Open all the unread URLs in the current feed and mark them as read. help (default key: ?) Run the help screen. toggle-source-view (default key: Ctrl + U) Toggle between the HTML view and the source view in the article view. toggle-article-read (default key: Shift + N) Toggle the read flag for the currently selected article, and clear the delete flag if set. toggle-show-read-feeds (default key: L) Toggle whether read feeds should be shown in the feed list. show-urls (default key: U) Show all URLs in the article in a list (similar to urlview). clear-tag (default key: Ctrl + T) Clear current tag. set-tag (default key: T) Select tag. open-search (default key: /) Open the search dialog. When a search is done in the article list, then the search operation only applies to the articles of the current feed, otherwise to all articles. goto-url (default key: #) Open the URL dialog and then open a specified URL in the browser. one (default key: 1) Open URL 1 in the browser. two (default key: 2) Open URL 2 in the browser. three (default key: 3) Open URL 3 in the browser. four (default key: 4) Open URL 4 in the browser. five (default key: 5) Open URL 5 in the browser. six (default key: 6) Open URL 6 in the browser. seven (default key: 7) Open URL 7 in the browser. eight (default key: 8) Open URL 8 in the browser. nine (default key: 9) Open URL 9 in the browser. zero (default key: 0) Open URL 10 in the browser. cmd-one (default key: 1) Start cmdline with 1. cmd-two (default key: 2) Start cmdline with 2. cmd-three (default key: 3) Start cmdline with 3. cmd-four (default key: 4) Start cmdline with 4. cmd-five (default key: 5) Start cmdline with 5. cmd-six (default key: 6) Start cmdline with 6. cmd-seven (default key: 7) Start cmdline with 7. cmd-eight (default key: 8) Start cmdline with 8. cmd-nine (default key: 9) Start cmdline with 9. enqueue (default key: E) Add the podcast download URL of the current article (if any is found) to the podcast download queue. See the PODCAST SUPPORT section for more information. edit-urls (default key: Shift + E) Edit the list of subscribed URLs. If a command is specified, Newsboat will replace the placeholders and then run the command. Newsboat sup- ports the following placeholders in the command: %f (path to urls file), %L (line number of the current feed (or feed of the currently selected article) in the urls file, or 0 if the feed URL originates outside of the urls file). If no command is specified, Newsboat will start the editor configured through the VISUAL environment variable (if unset, EDITOR is used; fallback: vi). When editing is finished, News- boat will reload the URLs file. Example config: bind E feedlist,arti- clelist,searchresultslist edit-urls "vim +%L %f" reload-urls (default key: Ctrl + R) Reload the URLs configuration file. redraw (default key: Ctrl + L) Redraw the screen. cmdline (default key: :) Open the command line with optional string already filled in. Example configuration: bind c everywhere cmdline "source ~/.newsboat/config" set-filter (default key: Shift + F) Set a filter. select-filter (default key: F) Select a predefined filter. clear-filter (default key: Ctrl + F) Clear currently set filter. bookmark (default key: Ctrl + B) Bookmark currently selected article or URL. edit-flags (default key: Ctrl + E) Edit the flags of the currently selected article. next-unread-feed (default key: Ctrl + N) Go to the next feed with unread articles. This only works from the ar- ticle list. prev-unread-feed (default key: Ctrl + P) Go to the previous feed with unread articles. This only works from the article list. next-feed (default key: J) Go to the next feed. This only works from the article list. prev-feed (default key: K) Go to the previous feed. This only works from the article list. delete-article (default key: Shift + D) Delete the currently selected article. delete-all-articles (default key: Ctrl + D) Delete all articles in the articlelist. Note that the articlelist might contain a subset of feed's articles (because of filters or show-read-articles no), or it might contain a mix of articles from dif- ferent feeds (if you're viewing a query feed) a in either case, delete-all-articles affects just those articles, not all articles of the respective feed(s). purge-deleted (default key: $) Purge all articles that are marked as deleted from the article list. view-dialogs (default key: V) View list of open dialogs. close-dialog (default key: Ctrl + X) Close currently selected dialog. next-dialog (default key: Ctrl + V) Go to next dialog. prev-dialog (default key: Ctrl + G) Go to previous dialog. pipe-to (default key: |) Pipe article to command. The text will be word-wrapped according to the text-width setting. sort (default key: G) Sort feeds/articles by interactively choosing the sort method. rev-sort (default key: Shift + G) Sort feeds/articles by interactively choosing the sort method (re- versed). up (default key: UP) Go up one item in the list. down (default key: DOWN) Go down one item in the list. pageup (default key: PPAGE) Go up one page in the list. pagedown (default key: NPAGE) Go down one page in the list. halfpageup (default key: n/a) Go up half a page. halfpagedown (default key: n/a) Go down half a page. home (default key: HOME) Go to the first item in the list. end (default key: END) Go to the last item in the list. macro-prefix (default key: ,) Initiate macro execution. The next key press selects the actual macro and runs it. switch-focus (default key: TAB) Switch focus between widgets. This is currently only applicable to the filebrowser and dirbrowser contexts. goto-title (default key: n/a) Go to item whose title contains the specified string (case-insensi- tive). prevsearchresults (default key: Z) Return to previous search results (if any). This only works from searchresultslist. article-feed (default key: n/a) Go to the feed of the currently selected article. FORMAT STRINGS 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 % charac- ter, 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: Table 1. Available Identifiers for feedlist-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | d | Feed description | +------------+-----------------------------+ | | | | i | Feed index | +------------+-----------------------------+ | | | | l | Feed link | +------------+-----------------------------+ | | | | L | Feed RSS URL | +------------+-----------------------------+ | | | | n | "unread" flag field | +------------+-----------------------------+ | | | | S | download status | +------------+-----------------------------+ | | | | t | Feed title | +------------+-----------------------------+ | | | | T | First tag of a feed in the | | | URLs file | +------------+-----------------------------+ | | | | u | "unread/total" field | +------------+-----------------------------+ | | | | U | "unread" field | +------------+-----------------------------+ | | | | c | "total" field | +------------+-----------------------------+ 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"). Table 2. Available Identifiers for articlelist-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | a | Article author | +------------+-----------------------------+ | | | | D | Publication date. This can | | | be tweaked further with | | | datetime-format | +------------+-----------------------------+ | | | | f | Two characters: 1) "N" if | | | article is unread, "D" if | | | article is deleted, a space | | | otherwise; 2) "!" if arti- | | | cle has flags, a space oth- | | | erwise. | +------------+-----------------------------+ | | | | n | "unread" field | +------------+-----------------------------+ | | | | d | "deleted" field | +------------+-----------------------------+ | | | | F | Article flags | +------------+-----------------------------+ | | | | i | Article index | +------------+-----------------------------+ | | | | t | Article title | +------------+-----------------------------+ | | | | T | If the article list dis- | | | plays articles from differ- | | | ent feeds, then this iden- | | | tifier contains the title | | | of the feed to which the | | | article belongs. | +------------+-----------------------------+ | | | | L | Article length | +------------+-----------------------------+ | | | | e | Article enclosure URL | +------------+-----------------------------+ Table 3. Available Identifiers for selecttag-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | i | Line's index in the list | +------------+-----------------------------+ | | | | T | The tag this line corre- | | | sponds to | +------------+-----------------------------+ | | | | f | Number of unread feeds un- | | | der this tag | +------------+-----------------------------+ | | | | n | Number of unread articles | | | in feeds tagged with this | | | tag | +------------+-----------------------------+ | | | | u | Number of feeds tagged with | | | this tag | +------------+-----------------------------+ Table 4. Available Identifiers for notify-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | n | Number of unread articles | +------------+-----------------------------+ | | | | f | Number of unread feeds | +------------+-----------------------------+ | | | | d | Number of new unread arti- | | | cles (i.e. that were added | | | through the last reload) | +------------+-----------------------------+ | | | | D | Number of new unread feeds | | | (i.e. that were added | | | through the last reload) | +------------+-----------------------------+ Table 5. Available Identifiers for podlist-format +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | i | Download index | +------------+-----------------------------+ | | | | d | Currently downloaded size | | | in megabytes, displays one | | | digit of precision | +------------+-----------------------------+ | | | | t | Total download size in | | | megabytes, displays one | | | digit of precision | +------------+-----------------------------+ | | | | p | Downloaded precentage, dis- | | | plays one digit of preci- | | | sion | +------------+-----------------------------+ | | | | k | Download speed, displays | | | two digit of precision, al- | | | ways in KB/s (does not in- | | | clude the "KB/s" text) | +------------+-----------------------------+ | | | | K | Download speed, displays | | | two digit of precision, hu- | | | man readable (automatically | | | switches between KB/s, | | | MB/s, and GB/s) | +------------+-----------------------------+ | | | | S | Status of download, dis- | | | plays one of the folowing; | | | "queued", "downloading", | | | "ready", "canceled", | | | "deleted", "missing", | | | "played", "finished" or | | | "failed" | +------------+-----------------------------+ | | | | u | Url of the download | +------------+-----------------------------+ | | | | F | Absolute filename of the | | | download from the root di- | | | rectory (e.g. ~/down- | | | loads/podcast.mp3 -> | | | /home/name/downloads/pod- | | | cast.mp3) | +------------+-----------------------------+ | | | | b | Basename of the download | | | (e.g. /home/name/down- | | | loads/podcast.mp3 -> pod- | | | cast.mp3) | +------------+-----------------------------+ Table 6. Available Identifiers for download-path and download-filename-for- mat +------------+----------------------------------------------+ | | | | Identifier | Meaning | +------------+----------------------------------------------+ | | | | u | Filename part of the down- | | | load URL. May be empty. May | | | include a query string | | | <https://en.wikipedia.org/wiki/Query_string> | +------------+----------------------------------------------+ | | | | n | Name of the podcast feed | +------------+----------------------------------------------+ | | | | N | Name of the podcast feed. Contains the orig- | | | inal feed's name, even when selected through | | | a query feed | +------------+----------------------------------------------+ | | | | h | Name of the podcast feed's hostname | +------------+----------------------------------------------+ | | | | t | Title of the podcast episode | +------------+----------------------------------------------+ | | | | e | Extension of the podcast episode | +------------+----------------------------------------------+ | | | | F | Publication date of the podcast episode for- | | | matted as yyyy-mm-dd | +------------+----------------------------------------------+ | | | | m | Month when podcast episode was published | +------------+----------------------------------------------+ | | | | b | Abbreviated month name when podcast episode | | | was published | +------------+----------------------------------------------+ | | | | d | Day when podcast episode was published | +------------+----------------------------------------------+ | | | | H | Hour when podcast episode was published | +------------+----------------------------------------------+ | | | | M | Minute when podcast episode was published | +------------+----------------------------------------------+ | | | | S | Second when podcast episode was published | +------------+----------------------------------------------+ | | | | y | Year when podcast episode was published for- | | | matted as yy | +------------+----------------------------------------------+ | | | | Y | Year when podcast episode was published for- | | | matted as yyyy | +------------+----------------------------------------------+ Examples: feedlist-format "%4i %n %11u %t" articlelist-format "%4i %f %D %?T?|%-17T| ?%t" notify-format "%d new articles (%n unread articles, %f unread feeds)" podlist-format "%4i [%-5p %%] %-12S %F" DIALOG TITLES You can customize the title format of all available dialogs. Here is a list of dialogs with their respective title format configuration variables, and a list of available formats and their meaning. Please note that the title formats are localized, so if you work on a different locale that is sup- ported by Newsboat, the actually displayed title text may vary unless you customize it. Table 7. Dialog Title Formats +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Dialog | Configuration Vari- | Default Value | | | able | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Feed List | feedlist-title-for- | %N %V - %?F?Feeds&Your feeds? (%u unread, %t total)%?F? matching filter '%F'&?%?T? - tag '%T'&? | | | mat | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Article List | articlelist-ti- | %N %V - Articles in feed '%T' (%u unread, %t total)%?F? matching filter '%F'&? - %U | | | tle-format | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Search Result | searchresult-ti- | %N %V - Search results for '%s' (%u unread, %t total)%?F? matching filter '%F'&? | | | tle-format | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | File Browser | filebrowser-ti- | %N %V - %?O?Open File&Save File? - %f | | | tle-format | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Directory Browser | dirbrowser-ti- | %N %V - %?O?Open Directory&Save File? - %f | | | tle-format | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Help | help-title-format | %N %V - Help | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Select Tag Dialog | selecttag-title-for- | %N %V - Select Tag | | | mat | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Select Filter Dialog | selectfilter-ti- | %N %V - Select Filter | | | tle-format | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Article View | itemview-title-for- | %N %V - Article '%T' (%u unread, %t total) | | | mat | | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | URL View | urlview-title-format | %N %V - URLs | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ | | | | | Dialog List | dialogs-title-format | %N %V - Dialogs | +----------------------+----------------------+-------------------------------------------------------------------------------------------------+ Table 8. Common Title Format Identifiers +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | N | Name of the program, i.e. | | | "Newsboat" | +------------+-----------------------------+ | | | | V | Program version | +------------+-----------------------------+ Table 9. Feed List Title Format Identifiers +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | T | Currently selected tag | | | (empty if none selected) | +------------+-----------------------------+ | | | | t | Number of total feeds | +------------+-----------------------------+ | | | | u | Number of unread feeds | +------------+-----------------------------+ | | | | U | Number of unread articles | +------------+-----------------------------+ | | | | F | Current filter expression | | | (empty if no filter is ac- | | | tive) | +------------+-----------------------------+ Table 10. Article List Title Format Identifiers +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | T | Feed title | +------------+-----------------------------+ | | | | U | Feed URL | +------------+-----------------------------+ | | | | u | Number of unread articles | +------------+-----------------------------+ | | | | t | Number of total articles | +------------+-----------------------------+ | | | | F | Current filter expression | | | (empty if no filter is ac- | | | tive) | +------------+-----------------------------+ Table 11. Search Result Title Format Identifiers +-----------------------------+---------------+ | | | | Identifier | Meaning | +-----------------------------+---------------+ | | | | s | Search phrase | +-----------------------------+---------------+ | | | | a|Plus all the ones sup- | | | ported by articlelist-ti- | | | tle-format (see table | | | above) | | +-----------------------------+---------------+ Table 12. File Browser Title Format Identifiers +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | f | Current path | +------------+-----------------------------+ | | | | O | Non-empty if file browser | | | is in open mode, empty if | | | in save mode | +------------+-----------------------------+ Table 13. Directory Browser Title Format Identifiers +------------+-----------------------------+ | | | | Identifier | Meaning | +------------+-----------------------------+ | | | | f | Current path | +------------+-----------------------------+ | | | | O | Non-empty if directory | | | browser is in open mode, | | | empty if in save mode | +------------+-----------------------------+ Table 14. Article View Title Format Identifiers +------------+---------------------------+ | | | | Identifier | Meaning | +------------+---------------------------+ | | | | T | Article title | +------------+---------------------------+ | | | | F | Feed title | +------------+---------------------------+ | | | | u | Number of unread articles | +------------+---------------------------+ | | | | t | Number of total articles | +------------+---------------------------+ 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 se- lect 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 cus- tom 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 parame- ters, 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://sourceforge.net/p/snownews/code/ci/de3bd8b28191c4d4bc1be18275786613bcbc0c94/tree/docs/untested/> and filters <https://sourceforge.net/p/snownews/code/ci/9fb45e4cdf1cf9dea55b9af66c13a4c238809851/tree/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/ex- amples subdirectory. KILLFILES 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 tradition- ally called a "killfile", i.e. based on the content of this "killfile", ar- ticles that match certain conditions do not get displayed and are not pre- sented 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: ignore-article "https://synflood.at/blog/index.php?/feeds/index.rss2" "title =~ \"newsboat\"" ignore-article "regex:https?://nitter.net/.*" "title =~ \"^RT by\"" ignore-article "*" "title =~ \"Gentoo\"" It takes two parameters. The first one is either: * The URL of a feed. * A pattern prefixed with regex:. The pattern must be a POSIX <https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/V1_chap09.html> extended regular expression" , which will be matched case-insensitive. * "*" to match any feed (asterisk is not a pattern, glob or regexawe sim- ply reserve it to mean "all feeds"). The second argument is a filter expression for an article, probably in dou- ble 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 it- self can contain as many ignore-article commands as desired. You can also specify the way an article is ignored. There are two ways available: * During download: articles are ignored when a feed is downloaded and parsed, and thus won't be written to the local cache. * During display: articles are downloaded and written to the local cache, but are ignored when a feed is displayed. Both modes have their advantages and disadvantages: while the download ig- nore mode saves some storage, you cannot simply "undo" the ignore by remov- ing it from the configuration file: if an ignored article has already van- ished 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 con- figuration. The default ignore mode is "download". You can set the ignore-mode in the configuration file: ignore-mode "display" PODCAST SUPPORT 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 ex- ternal 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 "enclo- sures". Newsboat recognizes these enclosures and stores the relevant infor- mation 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! COMMAND LINE Like other text-oriented software, Newsboat contains an internal command- line to modify configuration variables ad hoc and to run own commands. It provides a flexible access to the functionality of Newsboat which is espe- cially 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 com- mands. Pressing the Enter key executes the command (possibly giving feed- back to the user) and closes the commandline. You can cancel entering com- mands by pressing the Esc key. The history of all the commands that you en- ter 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 influ- enced by setting the history-limit configuration variable. To disable his- tory 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 re- sults. If no match is found, no suggestion will be inserted into the com- mandline. For the set command, the completion also works for configuration variable names. In addition, some common key combination such as Ctrl + G (to cancel in- put), 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 vari- able history-limit) and also totally disabled (by setting said variable to 0). Currently, the following command line commands are available: quit Quit Newsboat q Alias for quit save <filename> Save current article to <filename> set <variable>[=<value>|&|!] Set (or get) configuration variable value. Specifying a ! after the name of a boolean configuration variable toggles their values, a & di- rectly after the name of a configuration variable of any type resets its value to the documented default value. tag <tagname> Select a certain tag goto <case-insensitive substring> Go to the next feed whose name contains the case-insensitive substring. source <filename> [...] Load the specified configuration files. This allows it to load alterna- tive configuration files or reload already loaded configuration files on-the-fly from the filesystem. dumpconfig <filename> Save current internal state of configuration to file, so that it can be instantly reused as configuration file. <number> Jump to the <number>th entry in the current dialog 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 mod- ern way, XDG Base Directory Specification <https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>, which splits the files between the following locations: 1. $XDG_CONFIG_HOME/newsboat/ (XDG_CONFIG_HOME defaults to ~/.config) 2. $XDG_DATA_HOME/newsboat/ (XDG_DATA_HOME defaults to ~/.local/share) 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 directo- ries, you should move the files as follows: config, urls to $XDG_CONFIG_HOME/newsboat/ cache.db, history.search, history.cmdline, queue to $XDG_DATA_HOME/newsboat/ 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 anywhereA a 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 | ~/.news- | $XDG_DATA_HOME/news- | | | boat/cache.db.lock | boat/cache.db.lock | +----------+--------------------+----------------------+ | | | | | Podboat | ~/.news- | $XDG_DATA_HOME/news- | | | boat/pb-lock.pid | boat/.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/config ~/.newsboat/urls XDG $XDG_CONFIG_HOME/newsboat/config $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 Tells Newsboat what browser to use if there is no browser setting in the config file. If this variable doesn't exist, a default of lynx(1) will be used. CURL_CA_BUNDLE Tells Newsboat to use the specified certificate file to verify the peer. The file may contain multiple certificates. The certificate(s) must be in PEM format. This option is useful if your libcurl is built without useful certifi- cate information, and you can't rebuild the library yourself. EDITOR Tells Newsboat what fallback editor to use when editing the urls file via the edit-urls operation and no VISUAL environment variable is set. If this variable doesn't exist either, a default of vi(1) will be used. NO_PROXY Tells Newsboat to ignore proxy setting for certain sites. 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.ex- ample.com". Domain names that start with a dot only match subdomains, e.g. ".example.com" matches "bar.example.com" but not "example.com" it- self. 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 Tells Newsboat what pager to use if the pager setting in the config file is explicitly set to an empty string. TMPDIR Tells Newsboat to use the specified directory for storing temporary files. If this variable doesn't exist, a default of /tmp will be used. VISUAL Tells Newsboat what editor to use when editing the urls file via the edit-urls operation. If this variable doesn't exist, the EDITOR envi- ronment variable will be used. XDG_CONFIG_HOME Tells Newsboat which base directory to use for the configuration files. See also the section on files for more information. XDG_DATA_HOME Tells Newsboat which base directory to use for the data files. See also the section on files for more information. SEE ALSO podboat(1) AUTHOR Alexander Batischev 2026-06-21 NEWSBOAT(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | FIRST STEPS | CONFIGURATION | CONFIGURATION COMMANDS | AVAILABLE OPERATIONS | FORMAT STRINGS | DIALOG TITLES | TAGGING | SCRIPTS AND FILTERS | KILLFILES | PODCAST SUPPORT | COMMAND LINE | FILES | ENVIRONMENT | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=newsboat&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>