kiss-repo

'\" t
.\"     Title: newsboat
.\"    Author: Alexander Batischev
.\" Generator: Asciidoctor 2.0.15
.\"      Date: 2021-03-21
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "NEWSBOAT" "1" "2021-03-21" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
newsboat \- an RSS/Atom feed reader for text terminals
.SH "SYNOPSIS"
.sp
\fBnewsboat\fP [\-r] [\-e] [\-i opmlfile] [\-u urlfile] [\-c cachefile] [\-C configfile] [\-X] [\-o] [\-x <command> ...] [\-h]
.SH "DESCRIPTION"
.sp
\fINewsboat\fP is an RSS/Atom feed reader for text terminals. RSS and Atom are a
number of widely\-used XML formats to transmit, publish and syndicate articles,
for example news or blog articles.  Newsboat is designed to be used on text
terminals on Unix or Unix\-like systems such as GNU/Linux, BSD or macOS.
.SH "OPTIONS"
.sp
\-h, \-\-help
.RS 4
Display help
.RE
.sp
\-r, \-\-refresh\-on\-start
.RS 4
Refresh feeds on start
.RE
.sp
\-e, \-\-export\-to\-opml
.RS 4
Export feeds as OPML to stdout
.RE
.sp
\-X, \-\-vacuum
.RS 4
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
\fBdoesn\(cqt\fP delete the entries; for that, see \fIcleanup\-on\-quit\fP,
\fIdelete\-read\-articles\-on\-quit\fP, \fIkeep\-articles\-days\fP, and \fImax\-items\fP
settings.
.RE
.sp
\-\-cleanup
.RS 4
Remove unreferenced entries from the cache and quit Newsboat. Feeds and
their articles will be removed if the feedurl is no longer in the
\fIurls\fP file.
.sp
Additionally, if the \fIdelete\-read\-articles\-on\-quit\fP configuration is set, all
read articles will be deleted (including articles of feeds which are still in
the \fIurls\fP file).
.RE
.sp
\-v, \-V, \-\-version
.RS 4
Get version information about Newsboat and the libraries it uses
.RE
.sp
\-i opmlfile, \-\-import\-from\-opml=opmlfile
.RS 4
Import an OPML file
.RE
.sp
\-u urlfile, \-\-url\-file=urlfile
.RS 4
Use an alternative URL file
.RE
.sp
\-c cachefile, \-\-cache\-file=cachefile
.RS 4
Use an alternative cache file
.RE
.sp
\-C configfile, \-\-config\-file=configfile
.RS 4
Use an alternative configuration file
.RE
.sp
\-x command ..., \-\-execute=command...
.RS 4
Execute one or more commands to run Newsboat unattended. Currently available
commands are "reload" and "print\-unread".
.RE
.sp
\-l loglevel, \-\-log\-level=loglevel
.RS 4
Generate a logfile with a certain loglevel. Valid loglevels are 1 to 6. An
actual logfile will only be written when you provide a logfile name.
.RE
.sp
\-d logfile, \-\-log\-file=logfile
.RS 4
Use this logfile as output when logging debug messages. Please note that this
only works when providing a loglevel.
.RE
.sp
\-E file, \-\-export\-to\-file=file
.RS 4
Export a list of read articles (resp. their GUIDs). This can be used to
transfer information about read articles between different computers.
.RE
.sp
\-I file, \-\-import\-from\-file=file
.RS 4
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.
.RE
.SH "FIRST STEPS"
.sp
After you\(cqve installed Newsboat, you can run it for the first time by typing
\f(CRnewsboat\fP on your command prompt. This will bring you the following message:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.sp
This means that Newsboat can\(cqt start without any configured feeds. To add
feeds to Newsboat, you can either add URLs to the configuration file
\fI~/.newsboat/urls\fP or you can import an OPML file by running \f(CRnewsboat \-i
blogroll.opml\fP. To manually add URLs, open the file with your favorite text
editor and add the URLs, one per line:
.sp
.if n .RS 4
.nf
.fam C
http://rss.cnn.com/rss/cnn_topstories.rss
http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml
.fam
.fi
.if n .RE
.sp
If you need to add URLs that have restricted access via username/password, simply
provide the username/password in the following way:
.sp
.if n .RS 4
.nf
.fam C
https://username:password@hostname.domain.tld/feed.rss
.fam
.fi
.if n .RE
.sp
In order to protect username and password, make sure that
\fI~/.newsboat/urls\fP is only readable by you and, optionally, your group:
.sp
.if n .RS 4
.nf
.fam C
$ chmod u=rw,g=r,o= ~/.newsboat/urls
.fam
.fi
.if n .RE
.sp
Newsboat also makes sure that usernames and passwords within URLs aren\(cqt
displayed in its user interface. In case there is a \fI@\fP in the username, you
need to write it as \fI%40\fP instead so that it can be distinguished from the \fI@\fP
that separates the username/password part from the hostname part.
.sp
You can also configure local files as feeds, by prefixing the local path with
\f(CRfile://\fP and adding it to the \fIurls\fP file:
.sp
.if n .RS 4
.nf
.fam C
file:///var/log/rss_eventlog.xml
.fam
.fi
.if n .RE
.sp
Now you can run Newsboat again, and it will present you with a controllable
list of the URLs that you configured previously. You can now start downloading
the feeds, either by pressing "R" to download all feeds, or by pressing "r" to
download the currently selected feed. You can then select a feed you want to
read, and by pressing "Enter", you can go to the article list for this feed.
This works even while the downloading is still in progress.
.sp
You can now see the list of available articles by their title. A "N" on the
left indicates that an article wasn\(cqt read yet. Pressing "Enter" brings you to
the content of the article. You can scroll through this text, and also run
a browser (default: lynx) to view the complete article if the content is empty
or just an abstract or a short description. Each URL in the article has
a number next to it; to open it, type \f(CR#\fP and then the number, then press
"Enter". For single\-digit links, like 3, you can just press that number on the
keyboard.
.sp
Pressing "q" brings you back to the article list, and pressing "q" again brings
you back to the feed list. Pressing "q" a third time then closes Newsboat.
.sp
Newsboat caches the article that it downloads. This means that when you start
Newsboat again and reload a feed, the old articles can still be read even if
they aren\(cqt in the current RSS feeds anymore. Optionally you can configure how
many articles shall be preserved by feed so that the article backlog doesn\(cqt
grow endlessly (see \f(CRmax\-items\fP below).
.sp
Newsboat also uses a number of measures to preserve the users\(aq and feed
providers\(aq bandwidth, by trying to avoid unnecessary feed downloads through the
use of conditional HTTP downloading. It saves every feed\(cqs "Last\-Modified" and
"ETag" response header values (if present) and advises the feed\(cqs HTTP server
to only send data if the feed has been updated by modification date/time or
"ETag" header. This doesn\(cqt only make feed downloads for RSS feeds with no new
updates faster, it also reduces the amount of transferred data per request.
Conditional HTTP downloading can be optionally disabled per feed by using the
\f(CRalways\-download\fP configuration command.
.sp
Several aspects of Newsboat\(cqs behaviour can be configured via a configuration
file \fIconfig\fP, which is stored next to the \fIurls\fP file. This configuration file
contains lines in the form \f(CR<config\-command> <arg1> ...\fP.  The configuration
file can also contain comments, which start with the \f(CR#\fP character and go as
far as the end of line. If you need to enter a configuration argument that
contains spaces, use quotes (\f(CR"\fP) around the whole argument. It\(cqs even possible
to integrate the output of external commands into the configuration. The text
between two backticks (\f(CR`\fP) is evaluated as shell command, and its
output is put on its place instead. This works like backtick evaluation in
Bourne\-compatible shells and allows users to use external information from the
system within the configuration. Backticks and \f(CR#\fP characters can be escaped
with a backslash (e.g. \f(CR\(rs`\fP and \f(CR\(rs#\fP); in that
case, they\(cqll be replaced with literal \f(CR`\fP or \f(CR#\fP in the
configuration.
.sp
Searching for articles is possible in Newsboat, too. Just press the "/" key,
enter your search phrase, and the title and content of all articles are
searched for it. When you do a search from the list of feeds, all articles of
all feeds will be searched. When you do a search from the article list of a
feed, only the articles of the currently viewed feed are searched. When opening
an article from a search result dialog, the search phrase is highlighted.
.sp
The history of all your searches is saved to the filesystem, to the
\fIhistory.search\fP file (stored next to the \fIcache.db\fP file). By default, the
last 100 search phrases are stored, but this limited can be influenced through
the \f(CRhistory\-limit\fP configuration variable. To disable search
history saving, simply set the \f(CRhistory\-limit\fP to \f(CR0\fP.
.sp
Keys, as used in the bind\-key configuration command, use a special syntax.
Lowercase keys, uppercase keys and special characters are written literally.
The "Enter" key is written as \f(CRENTER\fP, "Tab" key as \f(CRTAB\fP, and the "Esc" key is
written as \f(CRESC\fP. The function keys "F1" to "F12" are written as \f(CRF1\fP to \f(CRF12\fP.
The "Space" key is written as \f(CRSPACE\fP. Key combinations with the "Ctrl" key,
such as "Ctrl\-R", are written as \f(CR^R\fP. Please be aware that all Ctrl\-related
key combinations need to be written in uppercase. The following identifiers for
keys are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRENTER\fP (Enter key)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRBACKSPACE\fP (backspace key)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRLEFT\fP (left cursor)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRRIGHT\fP (right cursor)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRUP\fP (up cursor)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRDOWN\fP (down cursor)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRPPAGE\fP (page up cursor)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRNPAGE\fP (page down cursor)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRHOME\fP (cursor to beginning of list/article)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CREND\fP (cursor to end of list/article)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRESC\fP (Esc key)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRTAB\fP (Tab key)
.RE
.sp
Newsboat also comes with user contributed content like scripts and color
themes. The user contributed content can be found in
\f(CR/usr/share/doc/newsboat/contrib/\fP. End users are encouraged to take a look as
they may find something useful.
.SH "CONFIGURATION COMMANDS"
.sp
\fIalways\-display\-description\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the description will always be displayed even if e.g. a \f(CR<content:encoded>\fP tag has been found. (example: always\-display\-description yes)
.RE
.sp
\fIalways\-download\fP (parameters: <url> [<url>...]; default value: \fIn/a\fP)
.RS 4
Specifies one or more feed URLs that should always be downloaded, regardless 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")
.RE
.sp
\fIarticle\-sort\-order\fP (parameters: <sortfield>[\-<direction>]; default value: \fIdate\fP)
.RS 4
The <sortfield> specifies which article property shall be used for sorting, currently available are: \f(CRdate\fP, \f(CRtitle\fP, \f(CRflags\fP, \f(CRauthor\fP, \f(CRlink\fP, \f(CRguid\fP and \f(CRrandom\fP. The optional <direction> specifies the sort direction. \f(CRasc\fP specifies ascending sorting, \f(CRdesc\fP specifies descending sorting. Note that direction does not affect \f(CRrandom\fP sort order. For \f(CRdate\fP, \f(CRdesc\fP is default, for all others, \f(CRasc\fP is default. (example: article\-sort\-order author\-desc)
.RE
.sp
\fIarticlelist\-format\fP (parameters: <format>; default value: \fI"%4i %f %D %6L  %?T?|%\-17T|  ?%t"\fP)
.RS 4
This variable defines the format of entries in the article list. See the respective section in the documentation for more information on format strings. (example: articlelist\-format "%4i %f %D   %?T?|%\-17T|  ?%t")
.RE
.sp
\fIarticlelist\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Articles in feed \(aq%T\(aq (%u unread, %t total)%?F? matching filter `%F\(aq&? \- %U" (localized)\fP)
.RS 4
Format of the title in article list. See "Format Strings" section of Newsboat manual for details on available formats. (example: articlelist\-title\-format "Articles in feed \(aq%T\(aq (%u unread)")
.RE
.sp
\fIauto\-reload\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, all feeds will be automatically reloaded at start up and then continuously after a certain time has passed (see \f(CRreload\-time\fP). (example: auto\-reload yes)
.RE
.sp
\fIbind\-key\fP (parameters: <key> <operation> [<dialog>]; default value: \fIn/a\fP)
.RS 4
Bind key <key> to <operation>. This means that whenever <key> is pressed, then <operation> is executed (if applicable in the current dialog). See [_newsboat_operations] and [_podboat_operations] for lists of available <operation> values. Optionally, you can specify a dialog. If you specify one, the key binding will only be added to the specified dialog. Available dialogs are \f(CRall\fP (default if none is specified), \f(CRfeedlist\fP, \f(CRfilebrowser\fP, \f(CRhelp\fP, \f(CRarticlelist\fP, \f(CRarticle\fP, \f(CRtagselection\fP, \f(CRfilterselection\fP, \f(CRurlview\fP, \f(CRpodboat\fP, and \f(CRdirbrowser\fP. (example: bind\-key ^R reload\-all)
.RE
.sp
\fIbookmark\-autopilot\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, 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)
.RE
.sp
\fIbookmark\-cmd\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
If set, then <command> will be used as bookmarking plugin. See the documentation on bookmarking for further information. (example: bookmark\-cmd "~/bin/delicious\-bookmark.sh")
.RE
.sp
\fIbookmark\-interactive\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the configured bookmark command is an interactive program. (example: bookmark\-interactive yes)
.RE
.sp
\fIbrowser\fP (parameters: <command>; default value: \fI%BROWSER, otherwise lynx\fP)
.RS 4
Set the browser command to use when opening an article in the browser. If the \f(CRBROWSER\fP environment variable is set, it will be used as the default browser, otherwise lynx will be used. Any occurrences of \f(CR%u\fP in <command> will be replaced by the URL being opened, enclosed in single quotes. Any occurrences of \f(CR%F\fP in <command> will be replaced by the feed\(cqs URL in single quotes. (example: browser "w3m %u")
.RE
.sp
\fIcache\-file\fP (parameters: <path>; default value: \fI"~/.newsboat/cache.db" or "~/.local/share/cache.db" (see "Files" section)\fP)
.RS 4
This configuration option sets the cache file. This is especially useful if the filesystem of your home directory doesn\(cqt support proper locking (e.g. NFS). (example: cache\-file "/tmp/testcache.db")
.RE
.sp
\fIcleanup\-on\-quit\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then the cache gets locked and superfluous feeds and items are removed, such as feeds that can\(cqt be found in the urls configuration file anymore. (example: cleanup\-on\-quit no)
.RE
.sp
\fIcolor\fP (parameters: <element> <fgcolor> <bgcolor> [<attribute> ...]; default value: \fIn/a\fP)
.RS 4
Set the foreground color, background color and optional attributes for a certain element. (example: color background white black)
.RE
.sp
\fIconfirm\-delete\-all\-articles\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then Newsboat will ask for confirmation whether the user wants to delete all articles. (example: confirm\-delete\-all\-articles no)
.RE
.sp
\fIconfirm\-mark\-all\-feeds\-read\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then Newsboat will ask for confirmation whether the user wants to mark all feeds as read. (example: confirm\-mark\-all\-feeds\-read no)
.RE
.sp
\fIconfirm\-exit\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then Newsboat will ask for confirmation whether the user really wants to quit Newsboat. (example: confirm\-exit yes)
.RE
.sp
\fIcookie\-cache\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
Set a cookie cache. If set, cookies will be cached in (i.e. read from and written to) this file, using \c
.URL "http://www.cookiecentral.com/faq/#3.5" "Netscape format" "."
(example: cookie\-cache "~/.newsboat/cookies.txt")
.RE
.sp
\fIdatetime\-format\fP (parameters: <date/time format>; default value: \fI%b %d\fP)
.RS 4
This format specifies the date/time format in the article list. For a detailed documentation on most of the allowed formats, consult the manpage 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")
.RE
.sp
\fIdefine\-filter\fP (parameters: <name> <filterexpr>; default value: \fIn/a\fP)
.RS 4
With this command, you can predefine filters, which you can later select from a list, and which are then applied after selection. This is especially useful for filters that you need often and you don\(cqt want to enter them every time you need them. (example: define\-filter "all feeds with \(aqfun\(aq tag" "tags # \(rs"fun\(rs"")
.RE
.sp
\fIdelete\-read\-articles\-on\-quit\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, all read articles will be deleted when quiting Newsboat. This option only applies if \f(CRcleanup\-on\-quit\fP is set to \f(CRyes\fP or if the \f(CR\-\-cleanup\fP argument is passed. (example: delete\-read\-articles\-on\-quit yes)
.RE
.sp
\fIdialogs\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Dialogs" (localized)\fP)
.RS 4
Format of the title in dialog list. See "Format Strings" section of Newsboat manual for details on available formats. (example: dialogs\-title\-format "%N %V \- Dialogs")
.RE
.sp
\fIdirbrowser\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- %?O?Open Directory&Save File? \- %f" (localized)\fP)
.RS 4
Format of the title in directory browser. See "Format Strings" section of Newsboat manual for details on available formats. (example: dirbrowser\-file\-format "%?O?Open Directory&Save File? \- %f")
.RE
.sp
\fIdisplay\-article\-progress\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then a read progress (in percent) is displayed in the article view. Otherwise, no read progress is displayed. (example: display\-article\-progress no)
.RE
.sp
\fIdownload\-full\-page\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, 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)
.RE
.sp
\fIdownload\-retries\fP (parameters: <number>; default value: \fI1\fP)
.RS 4
How many times Newsboat shall try to successfully download a feed before giving up. This is an option to improve the success of downloads on slow and shaky connections such as via a TOR proxy. (example: download\-retries 4)
.RE
.sp
\fIdownload\-timeout\fP (parameters: <number>; default value: \fI30\fP)
.RS 4
The number of seconds Newsboat shall wait when downloading a feed before giving up. This is an option to improve the success of downloads on slow and shaky connections such as via a TOR proxy. (example: download\-timeout 60)
.RE
.sp
\fIerror\-log\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
If set, then user errors (e.g. errors regarding defunct RSS feeds) will be logged to this file. (example: error\-log "~/.newsboat/error.log")
.RE
.sp
\fIexternal\-url\-viewer\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
If set, then \f(CRshow\-urls\fP will pipe the current article to a specific external tool instead of using the internal URL viewer. This can be used to integrate tools such as urlview. (example: external\-url\-viewer "urlview")
.RE
.sp
\fIfeed\-sort\-order\fP (parameters: <sortfield>[\-<direction>]; default value: \fInone\fP)
.RS 4
The <sortfield> specifies which feed property shall be used for sorting; currently available are: \f(CRfirsttag\fP, \f(CRtitle\fP, \f(CRarticlecount\fP, \f(CRunreadarticlecount\fP, \f(CRlastupdated\fP and \f(CRnone\fP. The optional <direction> specifies the sort direction. \f(CRasc\fP specifies ascending sorting, \f(CRdesc\fP specifies descending sorting. \f(CRdesc\fP is the default. (example: feed\-sort\-order firsttag)
.RE
.sp
\fIfeedhq\-flag\-share\fP (parameters: <flag>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIfeedhq\-flag\-star\fP (parameters: <flag>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIfeedhq\-login\fP (parameters: <login>; default value: \fI""\fP)
.RS 4
This variable sets your FeedHQ login for FeedHQ support. (example: feedhq\-login "your\-login")
.RE
.sp
\fIfeedhq\-min\-items\fP (parameters: <number>; default value: \fI20\fP)
.RS 4
This variable sets the number of articles that are loaded from FeedHQ per feed. (example: feedhq\-min\-items 100)
.RE
.sp
\fIfeedhq\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
This variable sets your FeedHQ password for FeedHQ support. Double quotes and backslashes within it should be escaped. (example: feedhq\-password "here_goesAquote:\(rs"")
.RE
.sp
\fIfeedhq\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: feedhq\-passwordfile "~/.newsboat/feedhq\-pw.txt")
.RE
.sp
\fIfeedhq\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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\-password.gpg")
.RE
.sp
\fIfeedhq\-show\-special\-feeds\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
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) appear in your subscription list. (example: feedhq\-show\-special\-feeds "no")
.RE
.sp
\fIfeedhq\-url\fP (parameters: <url>; default value: \fI"https://feedhq.org/"\fP)
.RS 4
Configures the URL where your FeedHQ instance resides. (example: feedhq\-url "https://feedhq.example.com/")
.RE
.sp
\fIfeedlist\-format\fP (parameters: <format>; default value: \fI"%4i %n %11u %t"\fP)
.RS 4
This variable defines the format of entries in the feed list. See the respective section in the documentation for more information on format strings. (example: feedlist\-format " %n %4i \- %11u \-%> %t")
.RE
.sp
\fIfeedlist\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- %?F?Feeds&Your feeds? (%u unread, %t total)%?F? matching filter `%F\(aq&?%?T? \- tag `%T\(aq&?" (localized)\fP)
.RS 4
Format of the title in feed list. See "Format Strings" section of Newsboat manual for details on available formats. (example: feedlist\-title\-format "Feeds (%u unread, %t total)")
.RE
.sp
\fIfilebrowser\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- %?O?Open File&Save File? \- %f" (localized)\fP)
.RS 4
Format of the title in file browser. See "Format Strings" section of Newsboat manual for details on available formats. (example: filebrowser\-title\-format "%?O?Open File&Save File? \- %f")
.RE
.sp
\fIgoto\-first\-unread\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then the first unread article will be selected whenever a feed is entered. (example: goto\-first\-unread no)
.RE
.sp
\fIgoto\-next\-feed\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, 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 \f(CRno\fP, then these keys will stop in the current feed. (example: goto\-next\-feed no)
.RE
.sp
\fIhelp\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Help" (localized)\fP)
.RS 4
Format of the title in help window. See "Format Strings" section of Newsboat manual for details on available formats. (example: help\-title\-format "%N %V \- Help")
.RE
.sp
\fIhighlight\fP (parameters: <target> <regex> <fgcolor> [<bgcolor> [<attribute> ...]]; default value: \fIn/a\fP)
.RS 4
With this command, you can highlight text parts in the feed list, the article list and the article view. For a detailed documentation, see the chapter on highlighting. (example: highlight all "newsboat" red)
.RE
.sp
\fIhighlight\-article\fP (parameters: <filterexpr> <fgcolor> <bgcolor> [<attribute> ...]; default value: \fIn/a\fP)
.RS 4
With this command, you can highlight articles in the article list if they match a filter expression. For a detailed documentation, see the chapter on highlighting. (example: highlight\-article "author =~ \(rs"Andreas Krennmair\(rs"" white red bold)
.RE
.sp
\fIhistory\-limit\fP (parameters: <number>; default value: \fI100\fP)
.RS 4
Defines the maximum number of entries of commandline resp. search history to be saved. To disable history saving, set it to 0. (example: history\-limit 0)
.RE
.sp
\fIhtml\-renderer\fP (parameters: <command>; default value: \fIinternal\fP)
.RS 4
If set to \f(CRinternal\fP, then the internal HTML renderer will be used. Otherwise, the specified command will be executed, the HTML to be rendered will be written to the command\(cqs stdin, and the program\(cqs 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")
.RE
.sp
\fIhttp\-auth\-method\fP (parameters: <method>; default value: \fIany\fP)
.RS 4
Set HTTP authentication method. Allowed values: \f(CRany\fP, \f(CRbasic\fP, \f(CRdigest\fP, \f(CRdigest_ie\fP (only available with libcurl 7.19.3 and newer), \f(CRgssnegotiate\fP, \f(CRntlm\fP and \f(CRanysafe\fP. (example: http\-auth\-method digest)
.RE
.sp
\fIignore\-article\fP (parameters: <feed> <filterexpr>; default value: \fIn/a\fP)
.RS 4
If a downloaded article from <feed> matches <filterexpr>, then it is ignored and not presented to the user. This command is further explained in the "kill file" section below. (example: ignore\-article "*" "title =~ \(rs"Windows\(rs"")
.RE
.sp
\fIignore\-mode\fP (parameters: [download/display]; default value: \fIdownload\fP)
.RS 4
This configuration option defines in what way an article is ignored (see \f(CRignore\-article\fP). If set to \f(CRdownload\fP, then it is ignored in the download/parsing phase and thus never written to the cache, if it set to \f(CRdisplay\fP, it is ignored when displaying articles but is kept in the cache. (example: ignore\-mode "display")
.RE
.sp
\fIinclude\fP (parameters: <path>; default value: \fIn/a\fP)
.RS 4
With this command, you can include other files to be interpreted as configuration files. This is especially useful to separate your configuration into several files, e.g. key configuration, color configuration, ... (example: include "~/.newsboat/colors")
.RE
.sp
\fIitemview\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Article \(aq%T\(aq (%u unread, %t total)" (localized)\fP)
.RS 4
Format of the title in article view. See "Format Strings" section of Newsboat manual for details on available formats. (example: itemview\-title\-format "Article \(aq%T\(aq")
.RE
.sp
\fIinoreader\-app\-id\fP (parameters: <string>; default value: \fI""\fP)
.RS 4
Unique application ID issued by Inoreader. See "Inoreader" section. (example: inoreader\-app\-id "123456789")
.RE
.sp
\fIinoreader\-app\-key\fP (parameters: <string>; default value: \fI""\fP)
.RS 4
Application key issued by Inoreader. See "Inoreader" section. (example: inoreader\-app\-key "TmV3c2JvYXQgcm9ja3MgOikK")
.RE
.sp
\fIinoreader\-flag\-share\fP (parameters: <flag>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIinoreader\-flag\-star\fP (parameters: <flag>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIinoreader\-login\fP (parameters: <login>; default value: \fI""\fP)
.RS 4
This variable sets your Inoreader login for Inoreader support. (example: inoreader\-login "your\-login")
.RE
.sp
\fIinoreader\-min\-items\fP (parameters: <number>; default value: \fI20\fP)
.RS 4
This variable sets the number of articles that are loaded from Inoreader per feed. (example: inoreader\-min\-items 100)
.RE
.sp
\fIinoreader\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
This variable sets your Inoreader password for Inoreader support. Double quotes and backslashes within it should be escaped. (example: inoreader\-password "here_goesAquote:\(rs"")
.RE
.sp
\fIinoreader\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: inoreader\-passwordfile "~/.newsboat/inoreader\-pw.txt")
.RE
.sp
\fIinoreader\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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/inoreader\-password.gpg")
.RE
.sp
\fIinoreader\-show\-special\-feeds\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
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: inoreader\-show\-special\-feeds "no")
.RE
.sp
\fIkeep\-articles\-days\fP (parameters: <number>; default value: \fI0\fP)
.RS 4
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\(cqt bring back the articles that were deleted earlier; currently, there\(cqs no non\-hacky way to bring back deleted articles. (example: keep\-articles\-days 30)
.RE
.sp
\fImacro\fP (parameters: <macro key> <command list>; default value: \fIn/a\fP)
.RS 4
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. (example: macro k open; reload; quit)
.RE
.sp
\fImark\-as\-read\-on\-hover\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then all articles that get selected in the article list are marked as read. (example: mark\-as\-read\-on\-hover yes)
.RE
.sp
\fImax\-download\-speed\fP (parameters: <number>; default value: \fI0\fP)
.RS 4
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)
.RE
.sp
\fImax\-browser\-tabs\fP (parameters: <number>; default value: \fI10\fP)
.RS 4
Set the maximum number of articles to open in a browser when using the \f(CRopen\-all\-unread\-in\-browser\fP or \f(CRopen\-all\-unread\-in\-browser\-and\-mark\-read\fP commands. (example: max\-browser\-tabs 4)
.RE
.sp
\fImax\-items\fP (parameters: <number>; default value: \fI0\fP)
.RS 4
Set the number of articles to maximally keep per feed. If the number is set to 0, then all articles are kept. (example: max\-items 100)
.RE
.sp
\fIminiflux\-login\fP (parameters: <username>; default value: \fI""\fP)
.RS 4
Sets the username for use with Miniflux. (example: miniflux\-login "admin")
.RE
.sp
\fIminiflux\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
Configures the password for use with Miniflux. Double quotes and backslashes within it should be escaped. (example: miniflux\-password "here_goesAquote:\(rs"")
.RE
.sp
\fIminiflux\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: miniflux\-passwordfile "~/.newsboat/miniflux\-pw.txt")
.RE
.sp
\fIminiflux\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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/miniflux\-password.gpg")
.RE
.sp
\fIminiflux\-url\fP (parameters: <url>; default value: \fI""\fP)
.RS 4
Configures the URL where the Miniflux installation you want to use resides. (example: miniflux\-url "https://example.com/miniflux/")
.RE
.sp
\fInewsblur\-login\fP (parameters: <login>; default value: \fI""\fP)
.RS 4
This variable sets your NewsBlur login for NewsBlur support. (example: newsblur\-login "your\-login")
.RE
.sp
\fInewsblur\-min\-items\fP (parameters: <number>; default value: \fI20\fP)
.RS 4
This variable sets the number of articles that are loaded from NewsBlur per feed. (example: newsblur\-min\-items 100)
.RE
.sp
\fInewsblur\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
This variable sets your NewsBlur password for NewsBlur support. Double quotes and backslashes within it should be escaped. (example: newsblur\-password "here_goesAquote:\(rs"")
.RE
.sp
\fInewsblur\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: newsblur\-passwordfile "~/.newsboat/newsblur\-pw.txt")
.RE
.sp
\fInewsblur\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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/newsblur\-password.gpg")
.RE
.sp
\fInewsblur\-url\fP (parameters: <url>; default value: \fI"https://newsblur.com"\fP)
.RS 4
Configures the URL where the NewsBlur instance resides. (example: newsblur\-url "https://localhost")
.RE
.sp
\fInotify\-always\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRno\fP, notifications will only be made when there are new feeds or articles. If set to \f(CRyes\fP, notifications will be made regardless. (example: notify\-always yes)
.RE
.sp
\fInotify\-beep\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the speaker will beep on new articles. (example: notify\-beep yes)
.RE
.sp
\fInotify\-format\fP (parameters: <string>; default value: \fI"newsboat: finished reload, %f unread feeds (%n unread articles total)" (localized)\fP)
.RS 4
Format string that is used for formatting notifications. See the chapter on format strings for more information. (example: notify\-format "%d new articles (%n unread articles, %f unread feeds)")
.RE
.sp
\fInotify\-program\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
If set, then the configured program will be executed if new articles arrived (through a reload) or if \f(CRnotify\-always\fP is \f(CRyes\fP. The first parameter 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: notify\-program "~/bin/my\-notifier")
.RE
.sp
\fInotify\-screen\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then a "privacy message" will be sent to the terminal, containing a notification message about new articles. This is especially useful if you use terminal emulations such as GNU screen which implement privacy messages. (example: notify\-screen yes)
.RE
.sp
\fInotify\-xterm\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the xterm window title will be set to a notification message about new articles. (example: notify\-xterm yes)
.RE
.sp
\fIocnews\-flag\-star\fP (parameters: <character>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIocnews\-login\fP (parameters: <username>; default value: \fI""\fP)
.RS 4
Sets the username to use with the ownCloud instance. (example: ocnews\-login "user")
.RE
.sp
\fIocnews\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
Configures the password to use with the ownCloud instance. Double quotes and backslashes within it should be escaped. (example: ocnews\-password "here_goesAquote:\(rs"")
.RE
.sp
\fIocnews\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: ocnews\-passwordfile "~/.newsboat/ocnews\-pw.txt")
.RE
.sp
\fIocnews\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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\-password.gpg")
.RE
.sp
\fIocnews\-url\fP (parameters: <url>; default value: \fI""\fP)
.RS 4
Configures the URL where the ownCloud instance resides. (example: ocnews\-url "https://localhost/owncloud")
.RE
.sp
\fIoldreader\-flag\-share\fP (parameters: <flag>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIoldreader\-flag\-star\fP (parameters: <flag>; default value: \fI""\fP)
.RS 4
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: oldreader\-flag\-star "b")
.RE
.sp
\fIoldreader\-login\fP (parameters: <login>; default value: \fI""\fP)
.RS 4
This variable sets your The Old Reader login for The Older Reader support. (example: oldreader\-login "your\-login")
.RE
.sp
\fIoldreader\-min\-items\fP (parameters: <number>; default value: \fI20\fP)
.RS 4
This variable sets the number of articles that are loaded from The Old Reader per feed. (example: oldreader\-min\-items 100)
.RE
.sp
\fIoldreader\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
This variable sets your The Old Reader password for The Old Reader support. Double quotes and backslashes within it should be escaped. (example: oldreader\-password "here_goesAquote:\(rs"")
.RE
.sp
\fIoldreader\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: oldreader\-passwordfile "~/.newsboat/oldreader\-pw.txt")
.RE
.sp
\fIoldreader\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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/oldreader\-password.gpg")
.RE
.sp
\fIoldreader\-show\-special\-feeds\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
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 articles) appear in your subscription list. (example: oldreader\-show\-special\-feeds "no")
.RE
.sp
\fIopenbrowser\-and\-mark\-jumps\-to\-next\-unread\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, jump to the next unread item when an item is opened in the browser and marked as read. (example: openbrowser\-and\-mark\-jumps\-to\-next\-unread yes)
.RE
.sp
\fIopml\-url\fP (parameters: <url> ...; default value: \fI""\fP)
.RS 4
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/anotheropmlfile.opml")
.RE
.sp
\fIpager\fP (parameters: [<command>/internal]; default value: \fIinternal\fP)
.RS 4
If set to \f(CRinternal\fP, 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 \f(CRPAGER\fP environment variable will be used. If the command contains a placeholder \f(CR%f\fP, it will be replaced with the temporary filename. (example: pager "less %f")
.RE
.sp
\fIpodcast\-auto\-enqueue\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then all podcast URLs that are found in articles are added to the podcast download queue. See the respective section in the documentation for more information on podcast support in Newsboat. (example: podcast\-auto\-enqueue yes)
.RE
.sp
\fIprepopulate\-query\-feeds\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then all query feeds are prepopulated with articles on startup. (example: prepopulate\-query\-feeds yes)
.RE
.sp
\fIssl\-verifyhost\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRno\fP, skip verification of the certificate\(cqs name against host. (example: ssl\-verifyhost no)
.RE
.sp
\fIssl\-verifypeer\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRno\fP, skip verification of the peer\(cqs SSL certificate. (example: ssl\-verifypeer no)
.RE
.sp
\fIproxy\-auth\-method\fP (parameters: <method>; default value: \fIany\fP)
.RS 4
Set proxy authentication method. Allowed values: \f(CRany\fP, \f(CRbasic\fP, \f(CRdigest\fP, \f(CRdigest_ie\fP (only available with libcurl 7.19.3 and newer), \f(CRgssnegotiate\fP, \f(CRntlm\fP and \f(CRanysafe\fP. (example: proxy\-auth\-method ntlm)
.RE
.sp
\fIproxy\-auth\fP (parameters: <auth>; default value: \fIn/a\fP)
.RS 4
Set the proxy authentication string. (example: proxy\-auth user:password)
.RE
.sp
\fIproxy\-type\fP (parameters: <type>; default value: \fIhttp\fP)
.RS 4
Set proxy type. Allowed values: \f(CRhttp\fP, \f(CRsocks4\fP, \f(CRsocks4a\fP, \f(CRsocks5\fP and \f(CRsocks5h\fP. (example: proxy\-type socks5)
.RE
.sp
\fIproxy\fP (parameters: <server:port>; default value: \fIn/a\fP)
.RS 4
Set the proxy to use for downloading RSS feeds. (Don\(cqt forget to actually enable the proxy with \f(CRuse\-proxy yes\fP.) (example: proxy localhost:3128)
.RE
.sp
\fIrefresh\-on\-startup\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then all feeds will be reloaded when Newsboat starts up. This is equivalent to the \f(CR\-r\fP commandline option. (example: refresh\-on\-startup yes)
.RE
.sp
\fIreload\-only\-visible\-feeds\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, 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)
.RE
.sp
\fIreload\-threads\fP (parameters: <number>; default value: \fI1\fP)
.RS 4
The number of parallel reload threads that shall be started when all feeds are reloaded. (example: reload\-threads 3)
.RE
.sp
\fIreload\-time\fP (parameters: <number>; default value: \fI60\fP)
.RS 4
The number of minutes between automatic reloads. (example: reload\-time 120)
.RE
.sp
\fIreset\-unread\-on\-update\fP (parameters: <url> [<url>...]; default value: \fIn/a\fP)
.RS 4
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 updates. This option can be specified multiple times. (example: reset\-unread\-on\-update "https://blog.fefe.de/rss.xml?html")
.RE
.sp
\fIrun\-on\-startup\fP (parameters: <list of operations>; default value: \fIn/a\fP)
.RS 4
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)
.RE
.sp
\fIsave\-path\fP (parameters: <path\-to\-directory>; default value: \fI~/\fP)
.RS 4
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")
.RE
.sp
\fIscrolloff\fP (parameters: <number>; default value: \fI0\fP)
.RS 4
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 center of the screen. (example: scrolloff 5)
.RE
.sp
\fIsearch\-highlight\-colors\fP (parameters: <fgcolor> <bgcolor> [<attribute> ...]; default value: \fIblack yellow bold\fP)
.RS 4
This configuration command specifies the highlighting colors when searching for text from the article view. (example: search\-highlight\-colors white black bold)
.RE
.sp
\fIsearchresult\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Search results (%u unread, %t total)%?F? matching filter `%F\(aq&?" (localized)\fP)
.RS 4
Format of the title in search result. See "Format Strings" section of Newsboat manual for details on available formats. (example: searchresult\-title\-format "Search result")
.RE
.sp
\fIselectfilter\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Select Filter" (localized)\fP)
.RS 4
Format of the title in filter selection dialog. See "Format Strings" section of Newsboat manual for details on available formats. (example: selectfilter\-title\-format "Select Filter")
.RE
.sp
\fIselecttag\-format\fP (parameters: <format>; default value: \fI"%4i  %T (%u)"\fP)
.RS 4
Format of the lines in "Select tag" dialog. See the respective section in the documentation for more information on format strings. (example: selecttag\-format "[%2i] %T (%n unread articles in %f feeds, %u feeds total)")
.RE
.sp
\fIselecttag\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- Select Tag" (localized)\fP)
.RS 4
Format of the title in tag selection dialog. See "Format Strings" section of Newsboat manual for details on available formats. (example: selecttag\-title\-format "Select Tag")
.RE
.sp
\fIshow\-keymap\-hint\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRno\fP, then the keymap hints on the bottom of screen will not be displayed. (example: show\-keymap\-hint no)
.RE
.sp
\fIshow\-title\-bar\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRno\fP, then the title bar on the top of the screen will not be displayed. (example: show\-title\-bar no)
.RE
.sp
\fIshow\-read\-articles\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then all articles of a feed are listed in the article list. If set to \f(CRno\fP, then only unread articles are listed. (example: show\-read\-articles no)
.RE
.sp
\fIshow\-read\-feeds\fP (parameters: [yes/no]; default value: \fIyes\fP)
.RS 4
If set to \f(CRyes\fP, then all feeds, including those without unread articles, are listed. If set to \f(CRno\fP, then only feeds with one or more unread articles are list. (example: show\-read\-feeds no)
.RE
.sp
\fIsuppress\-first\-reload\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the first automatic reload will be suppressed if \f(CRauto\-reload\fP is set to \f(CRyes\fP. (example: suppress\-first\-reload yes)
.RE
.sp
\fIswap\-title\-and\-hints\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the title at the top of screen and keymap hints at the bottom of screen will be swapped. (example: swap\-title\-and\-hints yes)
.RE
.sp
\fItext\-width\fP (parameters: <number>; default value: \fI0\fP)
.RS 4
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. Does not apply when using external renderer or viewing the source. Also note that "Link" header and "Links" section won\(cqt be affected by it—they contain URLs which are better not wrapped. (example: text\-width 72)
.RE
.sp
\fItoggleitemread\-jumps\-to\-next\-unread\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, jump to the next unread item when an item\(cqs read status is toggled in the article list. (example: toggleitemread\-jumps\-to\-next\-unread yes)
.RE
.sp
\fIttrss\-flag\-publish\fP (parameters: <character>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIttrss\-flag\-star\fP (parameters: <character>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIttrss\-login\fP (parameters: <username>; default value: \fI""\fP)
.RS 4
Sets the username for use with Tiny Tiny RSS. (example: ttrss\-login "admin")
.RE
.sp
\fIttrss\-mode\fP (parameters: [multi/single]; default value: \fImulti\fP)
.RS 4
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")
.RE
.sp
\fIttrss\-password\fP (parameters: <password>; default value: \fI""\fP)
.RS 4
Configures the password for use with Tiny Tiny RSS. Double quotes and backslashes within it should be escaped. (example: ttrss\-password "here_goesAquote:\(rs"")
.RE
.sp
\fIttrss\-passwordfile\fP (parameters: <path>; default value: \fI""\fP)
.RS 4
A more secure alternative to the above, by storing your password elsewhere in your system. (example: ttrss\-passwordfile "~/.newsboat/ttrss\-pw.txt")
.RE
.sp
\fIttrss\-passwordeval\fP (parameters: <command>; default value: \fI""\fP)
.RS 4
Another secure alternative, 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\-password.gpg")
.RE
.sp
\fIttrss\-url\fP (parameters: <url>; default value: \fI""\fP)
.RS 4
Configures the URL where the Tiny Tiny RSS installation you want to use resides. (example: ttrss\-url "https://example.com/ttrss/")
.RE
.sp
\fIunbind\-key\fP (parameters: <key> [<dialog>]; default value: \fIn/a\fP)
.RS 4
Unbind key <key>. This means that no operation is called when <key> is pressed. 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 \f(CRbind\-key\fP above). If you specify one, the key binding will only be unbound for the specified dialog. (example: unbind\-key R)
.RE
.sp
\fIurls\-source\fP (parameters: <source>; default value: \fI"local"\fP)
.RS 4
This configuration command sets the source where URLs shall be retrieved from. By default, this is the \fIurls\fP file. Alternatively, you can set it to \f(CRopml\fP, which enables Newsboat\(cqs OPML online subscription mode, to \f(CRttrss\fP which enables Newsboat\(cqs Tiny Tiny RSS support, to \f(CRoldreader\fP, which enables Newsboat\(cqs The Old Reader support, to \f(CRnewsblur\fP, which enables NewsBlur support, to \f(CRfeedhq\fP for FeedHQ support, to \f(CRocnews\fP for ownCloud News support, to \f(CRinoreader\fP for Inoreader support, or to \f(CRminiflux\fP for Miniflux support. Query feed specifications will be read from the local urls file regardless of this setting. (example: urls\-source "oldreader")
.RE
.sp
\fIurlview\-title\-format\fP (parameters: <format>; default value: \fI"%N %V \- URLs" (localized)\fP)
.RS 4
Format of the title in URL view. See "Format Strings" section of Newsboat manual for details on available formats. (example: urlview\-title\-format "URLs")
.RE
.sp
\fIuse\-proxy\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, then the configured proxy will be used for downloading the RSS feeds. (example: use\-proxy yes)
.RE
.sp
\fIuser\-agent\fP (parameters: <string>; default value: \fI""\fP)
.RS 4
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")
.RE
.sp
\fIwrap\-scroll\fP (parameters: [yes/no]; default value: \fIno\fP)
.RS 4
If set to \f(CRyes\fP, moving down while on the last item in a list will wrap around to the top and vice versa. (example: wrap\-scroll yes)
.RE
.SH "AVAILABLE OPERATIONS"
.sp
\fIopen\fP (default key: \fIENTER\fP)
.RS 4
Open the currently selected feed or article.
.RE
.sp
\fIquit\fP (default key: \fIq\fP)
.RS 4
Quit the program or return to the previous dialog (depending on the context).
.RE
.sp
\fIhard\-quit\fP (default key: \fIQ\fP)
.RS 4
Quit the program without confirmation.
.RE
.sp
\fIreload\fP (default key: \fIr\fP)
.RS 4
Reload the currently selected feed.
.RE
.sp
\fIreload\-all\fP (default key: \fIR\fP)
.RS 4
Reload all feeds.
.RE
.sp
\fImark\-feed\-read\fP (default key: \fIA\fP)
.RS 4
Mark all articles in the currently selected feed read.
.RE
.sp
\fImark\-all\-feeds\-read\fP (default key: \fIC\fP)
.RS 4
Mark articles in all feeds read.
.RE
.sp
\fImark\-all\-above\-as\-read\fP (default key: \fIn/a\fP)
.RS 4
Mark all above as read.
.RE
.sp
\fIsave\fP (default key: \fIs\fP)
.RS 4
Export the currently selected article to a plain text file.
.RE
.sp
\fIsave\-all\fP (default key: \fIn/a\fP)
.RS 4
Export all articles from the currently selected feed to plain text files.
.RE
.sp
\fInext\-unread\fP (default key: \fIn\fP)
.RS 4
Jump to the next unread article.
.RE
.sp
\fIprev\-unread\fP (default key: \fIp\fP)
.RS 4
Jump to the previous unread article.
.RE
.sp
\fInext\fP (default key: \fIJ\fP)
.RS 4
Jump to next list entry.
.RE
.sp
\fIprev\fP (default key: \fIK\fP)
.RS 4
Jump to previous list entry.
.RE
.sp
\fIrandom\-unread\fP (default key: \fI^K\fP)
.RS 4
Jump to a random unread article.
.RE
.sp
\fIopen\-in\-browser\fP (default key: \fIo\fP)
.RS 4
Use browser to open the URL associated with the current article, feed, or entry in the URL view.
.RE
.sp
\fIopen\-in\-browser\-noninteractively\fP (default key: \fIo\fP)
.RS 4
Use browser to open the URL associated with the current article, feed, or entry in the URL view. This operation works similar to \f(CRopen\-in\-browser\fP, but the output of the browser (stdout and stderr) is not shown, and the browser doesn\(cqt receive keyboard input. You would probably add \f(CR&\fP at the end of the \f(CRbrowser\fP command to put it into background, too.
.RE
.sp
\fIopen\-in\-browser\-and\-mark\-read\fP (default key: \fIO\fP)
.RS 4
Use browser to open the URL associated with the current article, or entry in the URL view. When used in the article list, it will also mark the article as read.
.RE
.sp
\fIopen\-all\-unread\-in\-browser\fP (default key: \fIn/a\fP)
.RS 4
Open all the unread URLs in the current feed.
.RE
.sp
\fIopen\-all\-unread\-in\-browser\-and\-mark\-read\fP (default key: \fIn/a\fP)
.RS 4
Open all the unread URLs in the current feed and mark them as read.
.RE
.sp
\fIhelp\fP (default key: \fI?\fP)
.RS 4
Run the help screen.
.RE
.sp
\fItoggle\-source\-view\fP (default key: \fI^U\fP)
.RS 4
Toggle between the HTML view and the source view in the article view.
.RE
.sp
\fItoggle\-article\-read\fP (default key: \fIN\fP)
.RS 4
Toggle the read flag for the currently selected article, and clear the delete flag if set.
.RE
.sp
\fItoggle\-show\-read\-feeds\fP (default key: \fIl\fP)
.RS 4
Toggle whether read feeds should be shown in the feed list.
.RE
.sp
\fIshow\-urls\fP (default key: \fIu\fP)
.RS 4
Show all URLs in the article in a list (similar to urlview).
.RE
.sp
\fIclear\-tag\fP (default key: \fI^T\fP)
.RS 4
Clear current tag.
.RE
.sp
\fIset\-tag\fP (default key: \fIt\fP)
.RS 4
Select tag.
.RE
.sp
\fIopen\-search\fP (default key: \fI/\fP)
.RS 4
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.
.RE
.sp
\fIgoto\-url\fP (default key: \fI#\fP)
.RS 4
Open the URL dialog and then open a specified URL in the browser.
.RE
.sp
\fIone\fP (default key: \fI1\fP)
.RS 4
Open URL 1 in the browser.
.RE
.sp
\fItwo\fP (default key: \fI2\fP)
.RS 4
Open URL 2 in the browser.
.RE
.sp
\fIthree\fP (default key: \fI3\fP)
.RS 4
Open URL 3 in the browser.
.RE
.sp
\fIfour\fP (default key: \fI4\fP)
.RS 4
Open URL 4 in the browser.
.RE
.sp
\fIfive\fP (default key: \fI5\fP)
.RS 4
Open URL 5 in the browser.
.RE
.sp
\fIsix\fP (default key: \fI6\fP)
.RS 4
Open URL 6 in the browser.
.RE
.sp
\fIseven\fP (default key: \fI7\fP)
.RS 4
Open URL 7 in the browser.
.RE
.sp
\fIeight\fP (default key: \fI8\fP)
.RS 4
Open URL 8 in the browser.
.RE
.sp
\fInine\fP (default key: \fI9\fP)
.RS 4
Open URL 9 in the browser.
.RE
.sp
\fIzero\fP (default key: \fI0\fP)
.RS 4
Open URL 10 in the browser.
.RE
.sp
\fIenqueue\fP (default key: \fIe\fP)
.RS 4
Add the podcast download URL of the current article (if any is found) to the podcast download queue (see the respective section in the documentation for more information on podcast support).
.RE
.sp
\fIedit\-urls\fP (default key: \fIE\fP)
.RS 4
Edit the list of subscribed URLs. Newsboat will start the editor configured through the \f(CRVISUAL\fP environment variable (if unset, \f(CREDITOR\fP is used; fallback: \f(CRvi\fP). When editing is finished, Newsboat will reload the URLs file.
.RE
.sp
\fIreload\-urls\fP (default key: \fI^R\fP)
.RS 4
Reload the URLs configuration file.
.RE
.sp
\fIredraw\fP (default key: \fI^L\fP)
.RS 4
Redraw the screen.
.RE
.sp
\fIcmdline\fP (default key: \fI:\fP)
.RS 4
Open the command line.
.RE
.sp
\fIset\-filter\fP (default key: \fIF\fP)
.RS 4
Set a filter.
.RE
.sp
\fIselect\-filter\fP (default key: \fIf\fP)
.RS 4
Select a predefined filter.
.RE
.sp
\fIclear\-filter\fP (default key: \fI^F\fP)
.RS 4
Clear currently set filter.
.RE
.sp
\fIbookmark\fP (default key: \fI^B\fP)
.RS 4
Bookmark currently selected article or URL.
.RE
.sp
\fIedit\-flags\fP (default key: \fI^E\fP)
.RS 4
Edit the flags of the currently selected article.
.RE
.sp
\fInext\-unread\-feed\fP (default key: \fI^N\fP)
.RS 4
Go to the next feed with unread articles. This only works from the article list.
.RE
.sp
\fIprev\-unread\-feed\fP (default key: \fI^P\fP)
.RS 4
Go to the previous feed with unread articles. This only works from the article list.
.RE
.sp
\fInext\-feed\fP (default key: \fIj\fP)
.RS 4
Go to the next feed. This only works from the article list.
.RE
.sp
\fIprev\-feed\fP (default key: \fIk\fP)
.RS 4
Go to the previous feed. This only works from the article list.
.RE
.sp
\fIdelete\-article\fP (default key: \fID\fP)
.RS 4
Delete the currently selected article.
.RE
.sp
\fIdelete\-all\-articles\fP (default key: \fI^D\fP)
.RS 4
Delete all articles in the articlelist. Note that the articlelist might contain a subset of feed\(cqs articles (because of filters or \f(CRshow\-read\-articles no\fP), or it might contain a mix of articles from different feeds (if you\(cqre viewing a query feed) — in either case, \f(CRdelete\-all\-articles\fP affects just those articles, not all articles of the respective feed(s).
.RE
.sp
\fIpurge\-deleted\fP (default key: \fI$\fP)
.RS 4
Purge all articles that are marked as deleted from the article list.
.RE
.sp
\fIview\-dialogs\fP (default key: \fIv\fP)
.RS 4
View list of open dialogs.
.RE
.sp
\fIclose\-dialog\fP (default key: \fI^X\fP)
.RS 4
Close currently selected dialog.
.RE
.sp
\fInext\-dialog\fP (default key: \fI^V\fP)
.RS 4
Go to next dialog.
.RE
.sp
\fIprev\-dialog\fP (default key: \fI^G\fP)
.RS 4
Go to previous dialog.
.RE
.sp
\fIpipe\-to\fP (default key: _| _)
.RS 4
Pipe article to command.
.RE
.sp
\fIsort\fP (default key: \fIg\fP)
.RS 4
Sort feeds/articles by interactively choosing the sort method.
.RE
.sp
\fIrev\-sort\fP (default key: \fIG\fP)
.RS 4
Sort feeds/articles by interactively choosing the sort method (reversed).
.RE
.sp
\fIup\fP (default key: \fIUP\fP)
.RS 4
Go up one item in the list.
.RE
.sp
\fIdown\fP (default key: \fIDOWN\fP)
.RS 4
Go down one item in the list.
.RE
.sp
\fIpageup\fP (default key: \fIPPAGE\fP)
.RS 4
Go up one page in the list.
.RE
.sp
\fIpagedown\fP (default key: \fINPAGE\fP)
.RS 4
Go down one page in the list.
.RE
.sp
\fIhome\fP (default key: \fIHOME\fP)
.RS 4
Go to the first item in the list.
.RE
.sp
\fIend\fP (default key: \fIEND\fP)
.RS 4
Go to the last item in the list.
.RE
.sp
\fImacro\-prefix\fP (default key: \fI,\fP)
.RS 4
Initiate macro execution. The next key press selects the actual macro and runs it.
.RE
.sp
\fIswitch\-focus\fP (default key: \fITAB\fP)
.RS 4
Switch focus between widgets. This is currently only applicable to the \f(CRfilebrowser\fP and \f(CRdirbrowser\fP contexts.
.RE
.sp
\fIgoto\-title\fP (default key: __)
.RS 4
Go to item whose title contains the specified string (case\-insensitive).
.RE
.SH "TAGGING"
.sp
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.
.sp
Usually, the \fIurls\fP 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 (\f(CR"\fP)
around the tag (see example below). An example \fIurls\fP file may look like this:
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE
.sp
When you now start Newsboat with this configuration, you can press "t" to select
a tag. When you select the tag "news", you will see all three RSS feeds. Pressing
"t" again and e.g. selecting the "conspiracy" tag, you will only see the
.URL "https://blog.fefe.de/rss.xml?html" "" ""
RSS feed. Pressing "^T" clears the current tag,
and again shows all RSS feeds, regardless of their assigned tags.
.sp
A special type of tag are tags that start with the tilde character (\f(CR~\fP). When such
a tag is found, the feed title is set to the tag name (excluding the \f(CR~\fP 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:
.sp
.if n .RS 4
.nf
.fam C
https://rss.orf.at/news.xml "~ORF News"
.fam
.fi
.if n .RE
.sp
Another special type of tag are tags that start with the exclamation mark (\f(CR!\fP). 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.
.sp
.if n .RS 4
.nf
.fam C
https://rss.orf.at/news.xml "!ORF News (hidden)"
.fam
.fi
.if n .RE
.SH "SCRIPTS AND FILTERS"
.sp
Newsboat contains support for Snownews extensions. The
RSS feed readers Snownews and Liferea share a common way of extending the
readers with custom scripts. Two mechanisms, namely "execurl" and "filter" type
scripts, are available and supported by Newsboat.
.sp
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.
.sp
The configuration is simple and straight\-forward. Just add to your \fIurls\fP file
configuration lines like the following ones:
.sp
.if n .RS 4
.nf
.fam C
exec:~/bin/execurl\-script
filter:~/bin/filter\-script:https://some.test/url
.fam
.fi
.if n .RE
.sp
The first line shows how to add an execurl script to your configuration: start
the line with \f(CRexec:\fP and then immediately append the path of the script that
shall be executed.  If this script requires additional parameters, simply use
quotes (see [_using_double_quotes] for details):
.sp
.if n .RS 4
.nf
.fam C
"exec:~/bin/execurl\-script param1 param2"
.fam
.fi
.if n .RE
.sp
The second line shows how to add a filter script to your configuration: start
the line with \f(CRfilter:\fP, then immediately append the path of the script, then
append a colon (\f(CR:\fP), 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:
.sp
.if n .RS 4
.nf
.fam C
"filter:~/bin/filter\-script param1 param2:https://url/foobar"
.fam
.fi
.if n .RE
.sp
In both cases, the tagging feature as described above is still available:
.sp
.if n .RS 4
.nf
.fam C
exec:~/bin/execurl\-script tag1 tag2 "quoted tag"
filter:~/bin/filter\-script:https://some.test/url tag3 tag4 tag5
.fam
.fi
.if n .RE
.sp
If you need to write your own extension, see
\c
.URL "https://web.archive.org/web/20090724045314/http://kiza.kcore.de/software/snownews/snowscripts/writing" "this
short guide"  for an introduction.
\c
.URL "https://github.com/kouya/snownews/tree/master/contrib" "A collection
of existing scripts"  might also help.
.sp
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 \fIdoc/examples\fP
subdirectory.
.SH "COMMAND LINE"
.sp
Like other text\-oriented software, Newsboat contains an internal commandline to
modify configuration variables ad hoc and to run own commands. It provides a flexible
access to the functionality of Newsboat which is especially useful for
advanced users.
.sp
To start the commandline, type ":". You will see a ":" prompt at the bottom of
the screen, similar to tools like vi(m) or mutt. You can now enter commands.
Pressing the "Enter" key executes the command (possibly giving feedback to the
user) and closes the commandline. You can cancel entering commands by pressing
the "Esc" key. The history of all the commands that you enter will be saved to
the \fIhistory.cmdline\fP file, stored next to the \fIcache.db\fP file. The backlog is
limited to 100 entries by default, but can be influenced by setting the
\f(CRhistory\-limit\fP configuration variable. To disable history
saving, set the \f(CRhistory\-limit\fP to \f(CR0\fP.
.sp
The commandline provides you with some help if you can\(cqt remember the full
names of commandline commands. By pressing the "Tab" key, Newsboat will try to
automatically complete your command. If there is more than one possible
completion, you can subsequently press the "Tab" key to cycle through all
results. If no match is found, no suggestion will be inserted into the
commandline. For the \f(CRset\fP command, the completion also works for configuration
variable names.
.sp
In addition, some common key combination such as "Ctrl\-G" (to cancel input),
"Ctrl\-K" (to delete text from the cursor position to the end of line), "Ctrl\-U" (to
clear the whole line) and "Ctrl\-W" (to delete the word before the current cursor
position) were added.
.sp
Please be aware that the input history of both the command line and the search
functions are saved to the filesystems, to the files \fIhistory.cmdline\fP resp.
\fIhistory.search\fP (stored next to the \fIcache.db\fP file). By default, the last 100
entries are saved, but this can be configured (configuration variable
\f(CRhistory\-limit\fP) and also totally disabled (by setting said
variable to \f(CR0\fP).
.sp
Currently, the following command line commands are available:
.sp
\fIquit\fP
.RS 4
Quit Newsboat
.RE
.sp
\fIq\fP
.RS 4
Alias for \fIquit\fP
.RE
.sp
\fIsave\fP <filename>
.RS 4
Save current article to <filename>
.RE
.sp
 \fIset\fP <variable>[=<value>|&|!]
.RS 4
Set (or get) configuration variable value. Specifying a \fI!\fP after the name of a boolean configuration variable toggles their values, a \fI&\fP directly after the name of a configuration variable of any type resets its value to the documented default value.
.RE
.sp
\fItag\fP <tagname>
.RS 4
Select a certain tag
.RE
.sp
\fIgoto\fP <case\-insensitive substring>
.RS 4
Go to the next feed whose name contains the case\-insensitive substring.
.RE
.sp
\fIsource\fP <filename> [...]
.RS 4
Load the specified configuration files. This allows it to load alternative configuration files or reload already loaded configuration files on\-the\-fly from the filesystem.
.RE
.sp
\fIdumpconfig\fP <filename>
.RS 4
Save current internal state of configuration to file, so that it can be instantly reused as configuration file.
.RE
.sp
\fI<number>\fP
.RS 4
Jump to the <number>th entry in the current dialog
.RE
.SH "FILES"
.sp
By default, Newsboat stores all the files in a traditional Unix fashion, i.e.
in a "dotdir" located at \fI~/.newsboat\fP. However, it also supports a modern
way,
.URL "https://standards.freedesktop.org/basedir\-spec/basedir\-spec\-latest.html" "XDG Base Directory Specification" ","
which splits the files between the following locations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI$XDG_CONFIG_HOME/newsboat/\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fI$XDG_DATA_HOME/newsboat/\fP
.RE
.sp
If the \f(CRXDG_CONFIG_HOME\fP environment variable is not set, Newsboat behaves as
if it was set to \fI~/.config\fP. Similarly, \f(CRXDG_DATA_HOME\fP defaults to
\fI~/.local/share\fP.
.sp
If the XDG config directory exists, Newsboat will use XDG directories, creating
the data directory if necessary. Otherwise, it will default to \fI~/.newsboat\fP.
.sp
If you\(cqre currently using \fI~/.newsboat/\fP but wish to migrate to XDG
directories, you should move the files as follows:
.sp
\fIconfig\fP, \fIurls\fP
.RS 4
to \fI$XDG_CONFIG_HOME/newsboat/\fP
.RE
.sp
\fIcache.db\fP, \fIhistory.search\fP, \fIhistory.cmdline\fP, \fIqueue\fP
.RS 4
to \fI$XDG_DATA_HOME/newsboat/\fP
.RE
.sp
Newsboat and Podboat also create "lock files". These prevent you from starting
two instances of the same program, and thus from corrupting your data. Newsboat
and Podboat remove these files when you quit the program, so there is no need
to copy them anywhere — just be aware of them in case you write scripts that
work with \fIcache.db\fP or \fIqueue\fP. By default, lock files are located as follows:
.TS
allbox tab(:);
lt lt lt.
T{
.sp

T}:T{
.sp
dotdir
T}:T{
.sp
XDG
T}
T{
.sp
Newsboat
T}:T{
.sp
\fI~/.newsboat/cache.db.lock\fP
T}:T{
.sp
\fI$XDG_DATA_HOME/newsboat/cache.db.lock\fP
T}
T{
.sp
Podboat
T}:T{
.sp
\fI~/.newsboat/pb\-lock.pid\fP
T}:T{
.sp
\fI$XDG_DATA_HOME/newsboat/.lock\fP
T}
.TE
.sp
.sp
Newsboat places the lock file next to the cache file, so if you specify
cache\-file setting or pass \f(CR\-\-cache\-file\fP command\-line argument,
the path to the lock file will change too. Podboat, on the other hand, always
places its lock file as shown above.
.sp
dotfiles
.RS 4
\fI~/.newsboat/config\fP
.sp
\fI~/.newsboat/urls\fP
.RE
.sp
XDG
.RS 4
\fI$XDG_CONFIG_HOME/newsboat/config\fP
.sp
\fI$XDG_CONFIG_HOME/newsboat/urls\fP
.sp
Note: if the \f(CRXDG_CONFIG_HOME\fP environment variable is not set, Newsboat behaves as if it was set to \fI~/.config\fP.
.RE
.SH "ENVIRONMENT"
.sp
\f(CRBROWSER\fP
.RS 4
Tells Newsboat what browser to use if there is no \f(CRbrowser\fP
setting in the config file. If this variable doesn\(cqt exist, a default
of \f(CRlynx(1)\fP will be used.
.RE
.sp
\f(CRCURL_CA_BUNDLE\fP
.RS 4
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.
.sp
This option is useful if your libcurl is built without useful
certificate information, and you can\(cqt rebuild the library yourself.
.RE
.sp
\f(CREDITOR\fP
.RS 4
Tells Newsboat what fallback editor to use when editing the \fIurls\fP file
via the \f(CRedit\-urls\fP operation and no \f(CRVISUAL\fP
environment variable is set. If this variable doesn\(cqt exist either, a
default of \f(CRvi(1)\fP will be used.
.RE
.sp
\f(CRPAGER\fP
.RS 4
Tells Newsboat what pager to use if the \f(CRpager\fP setting in
the config file is explicitly set to an empty string.
.RE
.sp
\f(CRTMPDIR\fP
.RS 4
Tells Newsboat to use the specified directory for storing temporary files.
If this variable doesn\(cqt exist, a default of \fI/tmp\fP will be used.
.RE
.sp
\f(CRVISUAL\fP
.RS 4
Tells Newsboat what editor to use when editing the \fIurls\fP file via the
\f(CRedit\-urls\fP operation. If this variable doesn\(cqt exist,
the \f(CREDITOR\fP environment variable will be used.
.RE
.sp
\f(CRXDG_CONFIG_HOME\fP
.RS 4
Tells Newsboat which base directory to use for the configuration files.
See also the section on files for more information.
.RE
.sp
\f(CRXDG_DATA_HOME\fP
.RS 4
Tells Newsboat which base directory to use for the data files. See also
the section on files for more information.
.RE
.SH "SEE ALSO"
.sp
podboat(1)
.SH "AUTHOR"
.sp
Alexander Batischev