NEWSBOAT(1)

📦

version 2.45 · 14 versions

2.45 · fedora 43, fedora 44 (latest)
2.37 · opensuse-leap 16.0
2.43 · nixos 26.05
2.45 · nixpkgs unstable
2.43 · alpine 3.24
2.45 · arch rolling
2.36 · ubuntu questing
2.21 · ubuntu jammy
2.39 · fedora 43
2.44 · fedora 43, fedora 44
2.43 · fedora 44
2.21 · debian bookworm
2.38 · ubuntu resolute, ubuntu stonking
2.36 · debian trixie

💖 NEWSBOAT(1) 💖

okay bestie, sit down, hydrate, and let me tell you about newsboat — it's an RSS/Atom feed reader for text terminals, and honestly? it's giving main character energy. this is the manual page, the newsboat(1) one, and we're gonna go through every single bit of it together. no cap. 🦋

✨ NAME ✨

newsboat — an RSS/Atom feed reader for text terminals 🌸

✨ SYNOPSIS ✨

newsboat [-r] [-e] [-i opmlfile] [-u urlfile] [-c cachefile] [-C
configfile] [-X] [-o] [-x command...] [-h]

like, that's the whole vibe in one line. look at her go. 💅

✨ DESCRIPTION ✨

Newsboat is an RSS/Atom feed reader for text terminals. and what even are RSS and Atom? they're a bunch of widely-used XML formats that transmit, publish, and syndicate articles — like news articles or blog articles. iconic behaviour honestly. 📰

and Newsboat is literally designed to be used on text terminals on Unix or Unix-like systems such as GNU/Linux, BSD, or macOS. no GUI, no nonsense, just you and the terminal, together forever. 🫶

✨ OPTIONS ✨

here's the full roster, bestie. every single one. i'm not skipping a single flag, that would be so not slay of me.

-h, --help — displays the help. the "hello, what do i do" button. 🙈
-r, --refresh-on-start — refreshes your feeds right when you start. no waiting, no clicking, just fresh feeds immediately. ⚡
-e, --export-to-opml — exports your feeds as OPML to stdout. heads up though: rn this outputs OPML 1.0, which means it loses all your tag information 😭 — but that's subject to change to 2.0 in the future, so watch this space.
--export-to-opml2 — exports your feeds as OPML 2.0, including tags, to stdout. yes the tags survive this time. 👑
-X, --vacuum — compacts the cache in two steps: 1) it reclaims the space that was left empty when data was deleted; and 2) it defragments the entries in the cache. and listen — this does not delete the entries. for actual deleting you want the cleanup-on-quit, delete-read-articles-on-quit, keep-articles-days, and max-items settings. 🧹
--cleanup — removes unreferenced entries from the cache and then quits Newsboat. feeds and their articles get removed if the feedurl is no longer in the urls file. Also, if the delete-read-articles-on-quit configuration is set, all read articles will be deleted — including articles of feeds that are still in the urls file. so like, be aware. 💀
-v, -V, --version — gets you version information about Newsboat and the libraries it uses. the receipts. 📜
-i opmlfile, --import-from-opml=opmlfile — imports an OPML file. 🎀
-u urlfile, --url-file=urlfile — uses an alternative URL file. 🦋
-c cachefile, --cache-file=cachefile — uses an alternative cache file. 🌸
-C configfile, --config-file=configfile — uses an alternative configuration file. ✨
--queue-file=queuefile — uses an alternative queue file. 💜
--search-history-file=searchhistoryfile — uses an alternative search history file. 🔍
--cmdline-history-file=cmdlinehistoryfile — uses an alternative command line history file. ⌨️
-x command ..., --execute=command... — executes one or more commands to run Newsboat unattended. the commands currently available are reload and print-unread. 🤖
-l loglevel, --log-level=loglevel — generates a logfile with a certain loglevel. valid values: 1 to 6, which are, in order, user error, critical, error, warning, info, and debug respectively. the filename can be specified with the --log-file option. if you don't specify one, a filename gets generated in the form newsboat_<date-time>.log. 📝
-d logfile, --log-file=logfile — uses this logfile as output when logging debug messages. ⚠️ please note that this only works when providing a loglevel. so don't come for me when it does nothing on its own.
-E file, --export-to-file=file — exports a list of read articles (resp. their GUIDs). you can use this to transfer information about read articles between different computers. 💾
-I file, --import-from-file=file — imports a list of read articles and marks them as read if they're held in the cache. this one is meant to be used in conjunction with the -E commandline parameter — they're a duo, a package deal. 🫂

🌈 FIRST STEPS 🌈

so you've installed Newsboat. congrats, you ate. 💅 now you run it for the first time by typing newsboat at your command prompt. and bestie, the first thing it's gonna hit you with is this:

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

and what that means, bestie, is that Newsboat can't start without any configured feeds. it's not being rude, it just has nothing to read. 😭

🎀 Adding Feeds 🎀

to add feeds to Newsboat you literally just add one feed URL per line to the ~/.newsboat/urls configuration file:

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

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

Adding comments — Lines that start with # can contain anything you want. Comments are ignored by Newsboat, but can serve as documentation for you. Please note, that commenting out URLs for debugging purposes might lead to unexpected data loss, see cleanup-on-quit for more details. ⚠️

Feeds with restricted access 🔒

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

https://username:password@hostname.domain.tld/feed.rss

in case there is a @ in the username, you need to write it as %40. yes, %40. not optional. 💅

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

$ chmod u=rw,g=r,o= ~/.newsboat/urls

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

Local files as feeds 📁

you can also configure local files as feeds — just prefix the local path with file:// and add 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 drill down through those views by pressing Enter, and you move back to the previous one by pressing Q. and pressing Q on the Feed List View — or pressing Shift + Q from anywhere — closes Newsboat. that's the exit, bestie, that's how you get out. 🚪

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. and when you open 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. and then you can:

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 number of articles is controlled by max-items. 🗂️

Caching — Newsboat uses a number of measures to preserve the users' and feed providers' bandwidth through the use of conditional HTTP downloading. It saves every feed's "Last-Modified" and "ETag" response header values (if present) and advises the feed's HTTP server to only send data if the feed has been updated. This doesn't only make feed downloads for RSS feeds with no new updates faster, it also reduces the amount of transferred data per request. ⚡ You can disable conditional HTTP downloading per feed by configuring always-download.

Article List View 📰

after you entered a feed, you can see the list of available articles by their title. a N on the left indicates that an article wasn't read yet. (rude of it to call you out like that, but okay.)

and then you can:

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.

and then you can:

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 complete article in a browser. The default browser is lynx. 🦁 You can use your browser of choice by configuring browser.

🌟 CONFIGURATION 🌟

several aspects of Newsboat can be configured via a config file, which is stored next to the urls file. a configuration line looks like this in general:

<config-command> <arg1> ...

the configuration file can contain comments, which start with the # character and go as far as the end of line. 📝

User contrib — Newsboat also comes with user contributed content like scripts and color themes. The user contributed content can be found in /usr/share/doc/newsboat/contrib/. End users are encouraged to take a look as they may find something useful. 🎨

🌈 Example 🌈

an example configuration looks like this:

# a comment
max-items        100 # such comments are possible, too
browser          links
show-read-feeds  no

unbind-key       R
bind             ^R feedlist reload-all

look at that. comments within lines. we love a flexible queen. 👑

✂️ 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. and 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"

okay so bestie, the thing about that backslash \ is that it does exactly one job: it makes Newsboat ignore the newline that comes right after it. That's it. That's the whole gig. It does not do anything else at all, no cap. 💅

So like, look at this super pretty formatted option:

ignore-article \
    "*" \
    "author =~ \"(\
        John Doe| \
        Mary Sue \
    )\""

bestie it does not become this:

ignore-article "*" "author =~ \"(John Doe|Mary Sue)\""

nope! Because literally only the newlines get yeeted, it actually turns into this monstrosity:

ignore-article     "*"     "author =~ \"(        John Doe|         Mary Sue     )\""

so for this reason 🫶 be so conscious of where you're splitting your lines, because it might genuinely matter. it's giving "the whitespace is load-bearing". 😭

✨ Using Double Quotes ✨

TL;DR — use double quotes for strings that contain spaces or double quotes. Escape double quotes (use \") and backslashes (use \\). Don't escape stuff outside of double quotes, and don't use single quotes for quoting — Newsboat does not support that. periodt.

A lot of Newsboat's options want strings as arguments — commands, passwords, dialog titles, URLs, the whole squad. Some options even take multiple strings at once. And those strings can have spaces in them, which lowkey confuses Newsboat since it already uses spaces to tell option names apart from option arguments. 🙈

So to help Newsboat understand your intent, wrap such strings in double quotes:

browser "firefox --new-tab %u"

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

ocnews-password "UnbalancedQuotes\"AreSoFun!"

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

pager "/usr/bin/my\\ favourite\\ pager"

the layers of escaping?? it's giving onion. 🧅✨

✨ Shell Evaluation ✨

It is also possible to integrate the output of external commands into the configuration. The text between two ` backticks is evaluated as a shell command, and its output is used. This works like backtick evaluation in Bourne-compatible shells and allows users to use external information from the system within the configuration. 🔥

✨ Escaping ✨

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

✨ Key Bindings ✨

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 operations) 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: text bind ab everywhere … bind abc everywhere … will only create a binding for abc. Re-ordering the commands will create 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 literally.

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

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 configured 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 globally, 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 configuration 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 literally.

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

The following identifiers for special keys are supported:

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 complete list of available operations see [_newsboat_operations] and [_podboat_operations].

💖 Dialog

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

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 following 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 attributes 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
listnormal_deleted: a deleted article-list item
listfocus_deleted: the currently selected deleted article-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 set a style for this element, then the info style gets used instead. no cap
hint-keys-delimiter (added in 2.25) — the comma that separates keys in the hints bar ✨ If you don't set a style for this element, then the info style gets used instead.
hint-separator (added in 2.25) — the colon separating keys from their descriptions in the hints bar 💅 If you don't set a style for this element, then the info style gets used instead.
hint-description (added in 2.25) — a description of a key in the hints bar 🌸 If you don't set a style for this element, then the info style gets used instead.
article — the article text 📖
end-of-text-marker — filler lines (~) below blocks of text 💀

And the default color configuration of Newsboat? It's giving this, bestie:

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 listnormal_deleted  white   black
color listfocus_deleted   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 ✨

okay this is the big one. every single knob you can turn in your config file, listed out. buckle up 🫶

always-display-description (parameters: [yes/no]; default value: no) — set it to yes and the description will always be displayed, even if, like, a <content:encoded> tag has been found. periodt. (example: always-display-description yes)
always-download (parameters: <url> [<url>...]; default value: n/a) — names one or more feed URLs that should always be downloaded, no matter what their Last-Modified timestamp and ETag header are saying 🙈 you can specify this option multiple times, she's flexible like that. (example: always-download "https://www.n-tv.de/23.rss")
article-sort-order (parameters: <sortfield>[-<direction>]; default value: date-asc) — the <sortfield> picks which article property is used for sorting. currently available: date, title, flags, author, link, guid, and random ✨ the optional <direction> is either asc for ascending or desc for descending. heads up: 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 the 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 inconsistencies will be fixed in a future major version of Newsboat, so don't @ me. (example: 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 info. (example: articlelist-format "%4i %f %D %?T?|%-17T| ?%t")
articlelist-title-format (parameters: <format>; default value: "%N %V - Articles in feed '%T' (%u unread, %t total)%?F? matching filter '%F'&? - %U" (localized)) — the format of the title in the article list 🎀 see the FORMAT STRINGS section of the Newsboat manual for the deets on available formats. (example: articlelist-title-format "Articles in feed '%T' (%u unread)")
auto-reload (parameters: [yes/no]; default value: no) — set it to yes and all feeds get automatically reloaded at start up, and then continuously after a certain time has passed (peep reload-time for that) 🔥 also see refresh-on-startup if you only wanna reload the feeds at start up and not continuously. and enabling suppress-first-reload omits the reload on start up. iykyk. (example: auto-reload yes)
bind (parameters: <key-sequence> <dialog>[,<dialog>] <command-list> [-- "<binding description>"]; default value: n/a) — binds a sequence of keys <key-sequence> to <command-list> 👑 meaning: whenever the keys in <key-sequence> get pressed in order, then the list of commands in <command-list> is executed (if applicable in the current dialog). for more info see Key Bindings. optionally, a description can be added — if present, it's shown in the help form 🌸 also see 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) — binds key <key> to <operation>. so whenever <key> is pressed, then <operation> is executed (if applicable in the current dialog) ✨ for more info see Old Style Key Bindings. also see unbind-key to remove a key binding. (example: bind-key ^R reload-all)
bookmark-autopilot (parameters: [yes/no]; default value: no) — set to yes and the configured bookmark command gets executed without any further input asked from the user — unless the url or the title can't be found/guessed 🫶 (example: bookmark-autopilot yes)
bookmark-cmd (parameters: <command>; default value: "") — if set, then <command> is used as the bookmarking plugin 💖 see the documentation on bookmarking for further info. (example: bookmark-cmd "~/bin/delicious-bookmark.sh")
bookmark-interactive (parameters: [yes/no]; default value: no) — set to yes and the configured bookmark command is an interactive program. iconic. (example: bookmark-interactive yes)
browser (parameters: <command>; default value: %BROWSER, otherwise lynx) — sets the browser command to use when opening an article in the browser 🌈 if the BROWSER environment variable is set, it'll be used as the default browser, otherwise lynx gets used. for more info, 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 config option sets the cache file 🎀 super useful if the filesystem of your home directory doesn't support proper locking (e.g. NFS, we've all been there). (example: cache-file "/tmp/testcache.db")
cleanup-on-quit (parameters: [yes/no/nudge]; default value: nudge) — set to yes and the cache gets locked and superfluous feeds and items get removed, like feeds that can't be found in the urls configuration 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) — sets 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) — set to yes and Newsboat asks for confirmation on whether the user wants to delete all articles. (example: confirm-delete-all-articles no)
confirm-exit (parameters: [yes/no]; default value: no) — set to yes and Newsboat asks for confirmation on whether the user really wants to quit Newsboat 😭 (example: confirm-exit yes)
confirm-mark-all-feeds-read (parameters: [yes/no]; default value: yes) — set to yes and Newsboat asks for confirmation on 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) — set to yes and Newsboat asks 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: "") — sets 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 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")
define-filter (parameters: <name> <filterexpr>; default value: n/a) — with this command you can predefine filters, which you can later select from a list, and which are then applied after selection ✨ especially useful for filters you need often and you don't wanna type them out every single time. (example: define-filter "all feeds with 'fun' tag" "tags # \"fun\"")
delete-read-articles-on-quit (parameters: [yes/no]; default value: no) — set to yes and all read articles get deleted when quitting 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 - Dialogs" (localized)) — format of the title in the dialog list 🎀 see the FORMAT STRINGS section of the Newsboat manual for the deets on available formats. (example: dialogs-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 the directory browser 👑 see the FORMAT STRINGS section of the Newsboat manual for the deets on available formats. (example: dirbrowser-file-format "%?O?Open Directory&Save File? - %f")
display-article-progress (parameters: [yes/no]; default value: yes) — set to yes and a read progress (in percent) gets displayed in the article view 💅 otherwise, no read progress is displayed. (example: display-article-progress no)
download-full-page (parameters: [yes/no]; default value: no) — set to yes and for all feed items with no content but with a link, the link gets downloaded and the result used as content instead 😳 this may significantly increase the download times of "empty" feeds, so like, be aware. (example: download-full-page yes)
download-retries (parameters: <number>; default value: 1) — how many times Newsboat is gonna try to download a feed before it's like "okay bestie I'm out" 🫠. it's literally here to help your downloads survive slow and shaky connections, like when you're routing through a TOR proxy. (example: download-retries 4)
download-timeout (parameters: <number>; default value: 30) — the number of seconds Newsboat waits on a feed download before giving up. same energy as above: it's for those slow, shaky connections (hello TOR proxy bestie 🧚). (example: download-timeout 60)
error-log (parameters: <path>; default value: "") — set this and all your user errors (like, say, defunct RSS feeds doing the absolute most) get logged to this file. (example: error-log "~/.newsboat/error.log")
external-url-viewer (parameters: <command>; default value: "") — set this and show-urls pipes the current article to a specific external tool instead of using the internal URL viewer. perfect for integrating tools like urlview, iykyk. (example: external-url-viewer "urlview")
feed-sort-order (parameters: <sortfield>[-<direction>]; default value: none) — <sortfield> picks which feed property gets used for sorting; rn the options are: firsttag, title, articlecount, unreadarticlecount, lastupdated, latestunread and none. the optional <direction> sets the sort direction: asc = ascending, desc = descending. desc is the default 💅. (example: feed-sort-order firsttag)
feedbin-flag-star (parameters: <flag>; default value: "") — if set and Feedbin support is on, then every article flagged with the specified flag gets "starred" in Feedbin and shows up in the list of "Starred items" ⭐. (example: feedbin-flag-star "b")
feedbin-login (parameters: <login>; default value: "") — sets your Feedbin login for Feedbin support. (example: feedbin-login "your-login")
feedbin-password (parameters: <password>; default value: "") — sets your Feedbin password for Feedbin support. double quotes and backslashes inside it need to be escaped, no cap. (example: feedbin-password "here_goesAquote:\"")
feedbin-passwordeval (parameters: <command>; default value: "") — a more secure alternative to the above: you provide your password from an external command that gets evaluated during login. great for reading your password from a gpg encrypted file or your system keyring 🔐. (example: feedbin-passwordeval "gpg --decrypt ~/.newsboat/feedbin-password.gpg")
feedbin-passwordfile (parameters: <path>; default value: "") — another alternative: stash your plaintext password elsewhere in your system. (example: feedbin-passwordfile "~/.newsboat/feedbin-pw.txt")
feedbin-url (parameters: <url>; default value: "https://api.feedbin.com") — configures the URL where the Feedbin installation you wanna use actually lives. (example: feedbin-url "https://example.com/feedbin/")
feedhq-flag-share (parameters: <flag>; default value: "") — if set and FeedHQ support is on, every article flagged with the specified flag gets "shared" in FeedHQ so the people who follow you can see it 👀. (example: feedhq-flag-share "a")
feedhq-flag-star (parameters: <flag>; default value: "") — if set and FeedHQ support is on, every article flagged with the specified flag gets "starred" in FeedHQ and appears in the list of "Starred items" ⭐. (example: feedhq-flag-star "b")
feedhq-login (parameters: <login>; default value: "") — sets your FeedHQ login for FeedHQ support. (example: feedhq-login "your-login")
feedhq-min-items (parameters: <number>; default value: 20) — sets how many articles get loaded from FeedHQ per feed. (example: feedhq-min-items 100)
feedhq-password (parameters: <password>; default value: "") — 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: "") — the more secure alternative to the above: your password comes from an external command evaluated during login. read it from a gpg encrypted file or your system keyring 🔐. (example: feedhq-passwordeval "gpg --decrypt ~/.newsboat/feedhq-password.gpg")
feedhq-passwordfile (parameters: <path>; default value: "") — another alternative: keep 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) show up 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 lives. (example: feedhq-url "https://feedhq.example.com/")
feedlist-format (parameters: <format>; default value: "%4i %n %11u %t") — defines the format of entries in the feed list. peep the FORMAT STRINGS section in the documentation for more info. (example: 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)) — the format of the title in the feed list. see the FORMAT STRINGS section of the Newsboat manual for the deets 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)) — the format of the title in the file browser. see the FORMAT STRINGS section of the Newsboat manual for all the available formats. (example: filebrowser-title-format "%?O?Open File&Save File? - %f")
freshrss-flag-star (parameters: <flag>; default value: "") — if set and FreshRSS support is used, every article flagged with the specified flag gets "starred" in FreshRSS and appears in the list of "Starred items" ⭐. (example: freshrss-flag-star "b")
freshrss-login (parameters: <login>; default value: "") — sets your FreshRSS login for FreshRSS support. (example: freshrss-login "your-login")
freshrss-min-items (parameters: <number>; default value: 20) — sets how many articles get loaded from FreshRSS per feed. (example: freshrss-min-items 100)
freshrss-password (parameters: <password>; default value: "") — 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: your password comes from an external command that gets evaluated during login. perfect for reading it from a gpg encrypted file or your system keyring 🔐. (example: freshrss-passwordeval "gpg --decrypt ~/.newsboat/freshrss-password.gpg")
freshrss-passwordfile (parameters: <path>; default value: "") — another alternative: store your plaintext password elsewhere in your system. (example: freshrss-passwordfile "~/.newsboat/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 (containing your starred/favourited articles) shows up 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.example.com/api/greader.php")
goto-first-unread (parameters: [yes/no]; default value: yes) — if it's yes, then the first unread article gets selected whenever you enter a feed 👑. (example: goto-first-unread no)
goto-next-feed (parameters: [yes/no]; default value: yes) — if it's yes, then the next-unread, prev-unread and random-unread keys will go searching in other feeds for unread articles if everything in the current feed is read. if it's no, those keys stop in the current feed, periodt. (example: goto-next-feed no)
help-title-format (parameters: <format>; default value: "%N %V - Help" (localized)) — the format of the title in the 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, peep the Colors section. (example: highlight all "newsboat" red)
highlight-article (parameters: <filterexpr> <fgcolor> <bgcolor> [<attribute> ...]; 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 =~ \"Andreas 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 max number of entries of commandline resp. search history that get saved. wanna disable history saving entirely? set it to 0. (example: history-limit 0)
html-renderer (parameters: <command>; default value: internal) — set this to internal and Newsboat uses its own built-in HTML renderer, periodt. Set it to literally anything else and that command gets run instead: the HTML that needs rendering gets piped into the command's stdin, and whatever the program spits out is what you see. Which is the whole point — it means you can drag in external renderers like w3m, links or lynx and let them do the glow-up. (example: html-renderer "w3m -dump -T text/html")
http-auth-method (parameters: <method>; default value: any) — picks the HTTP authentication method. The allowed values are any, basic, digest, digest_ie (heads up: 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 an article downloaded from <feed> matches <filterexpr>, it gets ignored and never shown to you. Not even a little peek. This one gets explained way more in the KILLFILES section below, so stay tuned. (example: ignore-article "*" "title =~ \"Windows\"")
ignore-mode (parameters: [download/display]; default value: download) — this is the vibe check for how an article gets ignored (see ignore-article above 👀). Set it to download and the ignoring happens in the download/parsing phase, so the article is never written to the cache at all. Set it to display and it gets ignored when it's time to show articles — but it's still chilling in the cache. (example: ignore-mode "display")
include (parameters: <path>; default value: n/a) — lets you pull other files in and have them read as config files too. Lowkey the best way to split your setup into several files — key config over here, color config over there... (example: include "~/.newsboat/colors")
inoreader-app-id (parameters: <string>; default value: "") — the unique application ID that Inoreader issues you. Peep the "Inoreader" section for the tea. (example: inoreader-app-id "123456789")
inoreader-app-key (parameters: <string>; default value: "") — the application key that Inoreader issues you. Again, "Inoreader" section, go look. (example: inoreader-app-key "TmV3c2JvYXQgcm9ja3MgOikK")
inoreader-flag-share (parameters: <flag>; default value: "") — if you set this and you're using Inoreader support, then every article flagged with the flag you picked gets "shared" on Inoreader, so the people who follow you can see it. Main character move fr. (example: inoreader-flag-share "a")
inoreader-flag-star (parameters: <flag>; default value: "") — if set and Inoreader support is on, every article flagged with your chosen flag gets "starred" in Inoreader and shows up in the "Starred items" list. (example: inoreader-flag-star "b")
inoreader-login (parameters: <login>; default value: "") — sets your Inoreader login so Inoreader support works. (example: inoreader-login "your-login")
inoreader-min-items (parameters: <number>; default value: 20) — how many articles get loaded from Inoreader per feed. (example: inoreader-min-items 100)
inoreader-password (parameters: <password>; default value: "") — your Inoreader password for Inoreader support. Double quotes and backslashes inside it need escaping. (example: inoreader-password "here_goesAquote:\"")
inoreader-passwordeval (parameters: <command>; default value: "") — the safer alternative to the option above 💅 you give it an external command, it gets evaluated during login, and that's how your password arrives. Chef's kiss for reading a password out of a gpg-encrypted file or your system keyring. (example: inoreader-passwordeval "gpg --decrypt ~/.newsboat/inoreader-password.gpg")
inoreader-passwordfile (parameters: <path>; default value: "") — yet another way: just stash your plaintext password somewhere else on your system. (example: inoreader-passwordfile "~/.newsboat/inoreader-pw.txt")
inoreader-show-special-feeds (parameters: [yes/no]; default value: yes) — if set and Inoreader support is in play, those "special feeds" like "Starred items" (your starred articles) and "Shared items" (your shared articles) show up in your subscription list. (example: inoreader-show-special-feeds "no")
itemview-title-format (parameters: <format>; default value: "%N %V - Article '%T' (%u unread, %t total)" (localized)) — the format of the title over in article view. Wanna know what all the format codes mean? The FORMAT STRINGS section of the Newsboat manual has you covered. (example: itemview-title-format "Article '%T'")
keep-articles-days (parameters: <number>; default value: 0) — set it to anything above 0 and only articles published within the last <number> days stick around — everything older gets deleted. Set it to 0 and this option just isn't active at all. ⚠️ real talk: flipping this setting will not resurrect articles that already got deleted. As of right now there's genuinely no non-hacky way to bring back deleted articles. Gone is gone bestie. (example: keep-articles-days 30)
keep-forever-if-flagged-with (parameters: <string>; default value: "") — if an item is older than what keep-articles-days allows, it still won't be deleted as long as it's carrying one of the flags you list here. Protection detail. 🛡️ (example: keep-forever-if-flagged-with f)
macro (parameters: <macro key> <command list> [-- "<macro description>"]; default value: n/a) — defines a macro key plus the list of commands that fire off when you hit the macro prefix and then that key. You can optionally tack on a description too — and if you do, it shows up 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) — set it to yes and literally every article you land on in the article list gets marked as read. Aggressive but valid. (example: mark-as-read-on-hover yes)
max-browser-tabs (parameters: <number>; default value: 10) — caps how many articles can get opened in a browser when you use the open-all-unread-in-browser or open-all-unread-in-browser-and-mark-read commands. No more 47-tab chaos. (example: max-browser-tabs 4)
max-download-speed (parameters: <number>; default value: 0) — set it above 0 and every download gets throttled to that limit, in KB/s. (example: max-download-speed 50)
max-items (parameters: <number>; default value: 0) — the max number of articles a feed is allowed to hold. Cross the threshold and the old ones get dropped. Set it to 0 and everything stays, forever. (example: max-items 100)
miniflux-flag-save (parameters: <flag>; default value: "") — if set and Miniflux support is on, every article flagged with your chosen flag gets saved to the external service you configured on your Miniflux instance. (example: miniflux-flag-save "b")
miniflux-flag-star (parameters: <flag>; default value: "") — if set and Miniflux support is on, every article flagged with your chosen flag gets "starred" in Miniflux and lands in the "Starred items" list. (example: miniflux-flag-star "b")
miniflux-login (parameters: <username>; default value: "") — sets the username Miniflux uses. (example: miniflux-login "admin")
miniflux-min-items (parameters: <number>; default value: 100) — how many articles get loaded from Miniflux per feed. (example: miniflux-min-items 20)
miniflux-password (parameters: <password>; default value: "") — configures the password for Miniflux. Double quotes and backslashes inside it need escaping. (example: miniflux-password "here_goesAquote:\"")
miniflux-passwordeval (parameters: <command>; default value: "") — the more secure route: hand over an external command, it gets evaluated during login, and your password comes from there. Perfect for reading it out of a gpg-encrypted file or your system keyring. ✨ (example: miniflux-passwordeval "gpg --decrypt ~/.newsboat/miniflux-password.gpg")
miniflux-passwordfile (parameters: <path>; default value: "") — the other option: keep your plaintext password somewhere else on your system. (example: miniflux-passwordfile "~/.newsboat/miniflux-pw.txt")
miniflux-show-special-feeds (parameters: [yes/no]; default value: yes) — if set and Miniflux support is on, a "Starred items" feed (packed with 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 Miniflux uses. (example: miniflux-token "E-uTqU8r55KucuHz26tJbXfrZVRndwY_mZAsEfcC8Bg=")
miniflux-tokeneval (parameters: <command>; default value: "") — the more secure alternative to the option above: give it an external command that's evaluated during login, and that's where your token comes from. Great for reading a token out of a gpg-encrypted file or your system keyring. (example: miniflux-tokeneval "gpg --decrypt ~/.newsboat/miniflux-token.gpg")
miniflux-tokenfile (parameters: <API Token>; default value: "") — another alternative: just store your plaintext token somewhere else on your system. (example: miniflux-tokenfile "~/.newsboat/miniflux-token.txt")
miniflux-url (parameters: <url>; default value: "") — configures the URL where the Miniflux installation you wanna use actually lives. (example: miniflux-url "https://example.com/miniflux/")
newsblur-login (parameters: <login>; default value: "") — sets your NewsBlur login for NewsBlur support. (example: newsblur-login "your-login")
newsblur-min-items (parameters: <number>; default value: 20) — how many articles get loaded from NewsBlur per feed. (example: newsblur-min-items 100)
newsblur-password (parameters: <password>; default value: "") — your NewsBlur password for NewsBlur support. Double quotes and backslashes inside it need escaping. (example: newsblur-password "here_goesAquote:\"")
newsblur-passwordeval (parameters: <command>; default value: "") — more secure version of the above: an external command gets evaluated during login, and that's how your password shows up. Ideal for pulling it from a gpg-encrypted file or your system keyring. 🫶 (example: newsblur-passwordeval "gpg --decrypt ~/.newsboat/newsblur-password.gpg")
newsblur-passwordfile (parameters: <path>; default value: "") — the other other alternative: store your plaintext password somewhere else on your system. (example: newsblur-passwordfile "~/.newsboat/newsblur-pw.txt")
newsblur-url (params: <url>; default: "https://newsblur.com") — this is where you tell Newsboat where your NewsBlur instance lives. (example: newsblur-url "https://localhost") 🦋
notify-always (params: [yes/no]; default: no) — set it to no and notifications only pop off when there's actually new feeds or articles, bestie. set it to yes and you get notified no matter what. (example: notify-always yes) 💅
notify-beep (params: [yes/no]; default: no) — yes means the speaker goes beep on new articles. iconic honestly. (example: notify-beep yes) 🔔
notify-format (params: <string>; default: "Newsboat: finished reload, %f unread feeds (%n unread articles total)" (localized)) — the format string used for formatting your notifications. (example: notify-format "%d new articles (%n unread articles, %f unread feeds)") ✨
notify-program (params: <command>; default: "") — set this and the program you name gets run when new articles arrive (via a reload), or when notify-always is yes. the first parameter handed to the called program is the notification message. wanna pass other hard-coded args? write a lil wrapper shell script and use that as your <command> instead. (example: notify-program "~/bin/my-notifier") 🫶
notify-screen (params: [yes/no]; default: no) — set it to yes and a "privacy message" gets sent to the terminal, containing a notification about new articles. this is highkey useful if you use terminal emulations like GNU screen that implement privacy messages. (example: notify-screen yes) 🌸
notify-xterm (params: [yes/no]; default: no) — yes means the xterm window title gets set to a notification message about new articles. (example: notify-xterm yes) 👑
ocnews-flag-star (params: <character>; default: "") — if set and you're using ownCloud News support, then every article flagged with the flag you specify gets "starred" in ownCloud News. (example: ocnews-flag-star "s") ⭐
ocnews-login (params: <username>; default: "") — sets the username to use with your ownCloud instance. (example: ocnews-login "user") 💖
ocnews-password (params: <password>; default: "") — configures the password to use with your ownCloud instance. double quotes and backslashes inside it should be escaped, fr. (example: ocnews-password "here_goesAquote:\"") 🔐
ocnews-passwordeval (params: <command>; default: "") — a more secure alternative to the above: hand over your password from an external command that gets evaluated during login. this can read your password from a gpg encrypted file or your system keyring. (example: ocnews-passwordeval "gpg --decrypt ~/.newsboat/ocnews-password.gpg") 🧚
ocnews-passwordfile (params: <path>; default: "") — another alternative: store your plaintext password elsewhere on your system. (example: ocnews-passwordfile "~/.newsboat/ocnews-pw.txt") 📁
ocnews-url (params: <url>; default: "") — configures the URL where the ownCloud instance resides. (example: ocnews-url "https://localhost/owncloud") 🌈
oldreader-flag-share (params: <flag>; default: "") — if set and The Old Reader support is used, then all articles flagged with the specified flag get "shared" in The Old Reader, so the people who follow you can see them. (example: oldreader-flag-share "a") 💜
oldreader-flag-star (params: <flag>; default: "") — if set and The Old Reader support is used, then all articles flagged with the specified flag get "starred" in The Old Reader and show up in the list of "Starred items". (example: oldreader-flag-star "b") ⭐
oldreader-login (params: <login>; default: "") — this variable sets your The Old Reader login for The Older Reader support. (example: oldreader-login "your-login") 🦋
oldreader-min-items (params: <number>; default: 20) — this variable sets how many articles get loaded from The Old Reader per feed. (example: oldreader-min-items 100) 🔢
oldreader-password (params: <password>; default: "") — this variable sets your The Old Reader password for The Old Reader support. double quotes and backslashes inside it should be escaped. (example: oldreader-password "here_goesAquote:\"") 🔐
oldreader-passwordeval (params: <command>; default: "") — a more secure alternative to the above: supply your password from an external command that gets evaluated during login. can read your password from a gpg encrypted file or your system keyring. (example: oldreader-passwordeval "gpg --decrypt ~/.newsboat/oldreader-password.gpg") 🧚
oldreader-passwordfile (params: <path>; default: "") — another alternative: store your plaintext password elsewhere on your system. (example: oldreader-passwordfile "~/.newsboat/oldreader-pw.txt") 📁
oldreader-show-special-feeds (params: [yes/no]; default: 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 articles) appear in your subscription list. (example: oldreader-show-special-feeds "no") ✨
openbrowser-and-mark-jumps-to-next-unread (params: [yes/no]; default: no) — if set to yes, jump to the next unread item whenever an item is opened in the browser and marked as read. (example: openbrowser-and-mark-jumps-to-next-unread yes) 🔥
opml-url (params: <url> ...; default: "") — if the OPML online subscription mode is enabled, then your feed list gets taken from the OPML file found at this location. optionally you can specify more than one URL — all the listed OPML URLs get taken into account when loading the feed list. (example: opml-url "https://host.domain.tld/blogroll.opml" "https://example.com/anotheropmlfile.opml") 🌐
pager (params: [<command>/internal]; default: internal) — set it to internal and the internal pager gets used. otherwise, the article to be displayed gets rendered into a temporary file and then shown with the pager you configured. if the command is an empty string, the content of the PAGER environment variable gets used. if the command contains a placeholder %f, it gets replaced with the temporary filename. (example: pager "less %f") 📖
podcast-auto-enqueue (params: [yes/no]; default: no) — set it to yes and every podcast URL found in articles gets added to the podcast download queue. peep the PODCAST SUPPORT section in the documentation for more. (example: podcast-auto-enqueue yes) 🎧
prepopulate-query-feeds (params: [yes/no]; default: no) — set it to yes and all query feeds get prepopulated with articles on startup. (example: prepopulate-query-feeds yes) 🍓
proxy (params: <server:port>; default: n/a) — sets the proxy to use for downloading RSS feeds. (don't forget to actually enable the proxy with use-proxy yes.) heads up that the NO_PROXY environment variable can disable the proxy for certain sites. (example: proxy localhost:3128) 🛰️
proxy-auth (params: <auth>; default: n/a) — sets the proxy authentication string. (example: proxy-auth user:password) 🔑
proxy-auth-method (params: <method>; default: any) — sets the 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 (params: <type>; default: http) — sets the proxy type. allowed values: http, socks4, socks4a, socks5 and socks5h. (example: proxy-type socks5) 🌐
refresh-on-startup (params: [yes/no]; default: no) — set it to yes and all feeds get reloaded when Newsboat starts up. this is equivalent to the -r commandline option. see also auto-reload to additionally reload the feeds continuously. (example: refresh-on-startup yes) 🔄
reload-only-visible-feeds (params: [yes/no]; default: no) — set it to yes and manually reloading all feeds will only reload the currently visible feeds, like if a filter or a tag is set. (example: reload-only-visible-feeds yes) 👀
reload-threads (params: <number>; default: 1) — how many parallel reload threads get started when all feeds are reloaded. (example: reload-threads 3) 🧵
reload-time (params: <number>; default: 60) — how many minutes between automatic reloads. (example: reload-time 120) ⏰
reset-unread-on-update (params: <url> [<url>...]; default: n/a) — names one or more feed URLs whose articles will have their unread flag reset if an article has been updated, i.e. its content changed. this is especially useful for RSS feeds where single articles get updated after publication and you wanna be notified of the updates. this option can be specified multiple times. (example: reset-unread-on-update "https://blog.fefe.de/rss.xml?html") 🔔
restrict-filename (params: [yes/no]; default: yes) — set it to no and Newsboat won't limit saved article filenames to ASCII characters. (example: restrict-filename no) 📝
run-on-startup (params: <list of operations>; default: n/a) — names one or more Newsboat operations, separated by semicolons, that get executed on Newsboat startup. (example: run-on-startup next-unread; open; random-unread; open) 🚀
save-path (params: <path-to-directory>; default: ~/) — the default path where articles get saved to. if you specify an invalid path, the current directory gets used. (example: save-path "~/Saved Articles") 💾
scrolloff (params: <number>; default: 0) — keeps 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) 📜
search-highlight-colors (params: <fgcolor> <bgcolor> [<attribute> ...]; default: black yellow bold) — this configuration command sets the highlighting colors when searching for text from the article view. for available colors and attributes, 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)) — this is the glow-up for the title in the search result screen. Peep the FORMAT STRINGS section of the Newsboat manual for all the format magic you can use. (example: searchresult-title-format "Search result")
selectfilter-title-format (parameters: <format>; default value: "%N %V - Select Filter" (localized)) — the title format for the filter selection dialog, bestie. FORMAT STRINGS section of the Newsboat manual has the deets on available formats. (example: selectfilter-title-format "Select Filter")
selecttag-format (parameters: <format>; default value: "%4i %T (%u)") — formats each line in the "Select tag" dialog, fr fr. Check the FORMAT STRINGS section in the docs for more. (example: selecttag-format "[%2i] %T (%n unread articles in %f feeds, %u feeds total)")
selecttag-title-format (parameters: <format>; default value: "%N %V - Select Tag" (localized)) — title format for the tag selection dialog, periodt. FORMAT STRINGS section of the Newsboat manual has the format details. (example: selecttag-title-format "Select Tag")
show-keymap-hint (parameters: [yes/no]; default value: yes) — set it to no and the keymap hints just don't show up anymore. (Those hints are usually chilling at the bottom of the screen, but lowkey check the swap-title-and-hints setting.) (example: show-keymap-hint no)
show-read-articles (parameters: [yes/no]; default value: yes) — yes means every article in a feed shows up in the article list. no means only the unread ones get listed. (example: show-read-articles no)
show-read-feeds (parameters: [yes/no]; default value: yes) — yes shows all feeds, even the ones with zero unread articles. no means only feeds with one or more unread articles are listed. (example: show-read-feeds no)
show-title-bar (parameters: [yes/no]; default value: yes) — set it to no and the title bar vanishes. (The title bar is usually up top, but see the swap-title-and-hints setting.) (example: show-title-bar no)
ssl-verifyhost (parameters: [yes/no]; default value: yes) — if you set it to no, it skips verifying the certificate's name against the host. (example: ssl-verifyhost no)
ssl-verifypeer (parameters: [yes/no]; default value: yes) — set to no and it skips verifying the peer's SSL certificate. (example: ssl-verifypeer no)
suppress-first-reload (parameters: [yes/no]; default value: no) — if set to yes, then that very first automatic reload gets suppressed when auto-reload is set to yes. (example: suppress-first-reload yes)
swap-title-and-hints (parameters: [yes/no]; default value: no) — set to yes and the title (usually up top) and the keymap hints (usually at the bottom) swap places, iconic behavior. You can hide both bars entirely with the show-keymap-hint and show-title-bar settings. (example: swap-title-and-hints yes)
text-width (parameters: <number>; default value: 0) — if you set it to a number greater than 0, all HTML gets rendered to this max line length, or the terminal width — whichever is smaller. If it's 0, the terminal width is always used in the article view, while pipe-to, save, and save-all wrap at 80 columns instead. Does not apply when you're using an external renderer or viewing the source. Also heads up: the "Link" header and "Links" section won't be affected by it — they hold URLs which are better left unwrapped. (example: text-width 72)
toggleitemread-jumps-to-next (parameters: [yes/no]; default value: yes) — set to yes, and you jump to the next item when you toggle an item's read status in the article list. Set to no, and the cursor just stays put 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, you jump to the next unread item when toggling an item's read status in the article list. If no, then the behavior is dictated by toggleitemread-jumps-to-next. (example: toggleitemread-jumps-to-next-unread yes)
ttrss-flag-publish (parameters: <character>; default value: "") — if you set this and you're using Tiny Tiny RSS support, then all articles flagged with the flag you specify get 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 in play, then all articles flagged with the flag you specify get "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 you use Tiny Tiny RSS in. In single-user mode, login and password are used for HTTP authentication, while in multi-user mode they're 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 inside it should be escaped, no cap. (example: ttrss-password "here_goesAquote:\"")
ttrss-passwordeval (parameters: <command>; default value: "") — a more secure alternative to the one above, bestie: hand over your password from an external command that gets evaluated during login. Great for reading your password from a gpg encrypted file or your system keyring. (example: ttrss-passwordeval "gpg --decrypt ~/.newsboat/ttrss-password.gpg")
ttrss-passwordfile (parameters: <path>; default value: "") — another option, storing your plaintext password elsewhere on 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 actually lives. (example: ttrss-url "https://example.com/ttrss/")
unbind-key (parameters: <key> [<dialog>]; default value: n/a) — unbinds key <key>, meaning nothing happens 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 pass "-a" as <key>, all currently bound keys become unbound. Optionally you can specify a dialog (for the list of available dialogs, see bind-key above) — if you specify one, the key binding is only unbound for that specific dialog. (example: unbind-key R)
urls-source (parameters: <source>; default value: "local") — this configuration command sets the source where URLs get retrieved from. By default it's 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 enables NewsBlur support; to feedbin for Feedbin support; to feedhq for FeedHQ support; to freshrss for FreshRSS support; to ocnews for ownCloud 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 "oldreader")
urlview-title-format (parameters: <format>; default value: "%N %V - URLs" (localized)) — the title format in the URL view. See the FORMAT STRINGS section of the Newsboat manual for details on available formats. (example: urlview-title-format "URLs")
use-proxy (parameters: [yes/no]; default value: no) — set to yes and the configured proxy gets used for downloading the RSS feeds. (example: use-proxy yes)
user-agent (parameters: <string>; default value: "") — if you set it to a non-zero-length string, that value becomes the 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) — set to yes and moving down while on the last item in a list wraps around to the top, and vice versa. Obsessed. (example: wrap-scroll yes)

✨ AVAILABLE OPERATIONS ✨

okay bestie, this is the big one — every single thing you can do in Newsboat, with the key it's bound to out of the box 💖. You can rebind literally all of these (iykyk, go check the CONFIGURATION COMMANDS part), but here's the stock vibe:

open (default key: ENTER) — open whatever feed or article you've currently got selected. the moment of truth ✨
quit (default key: Q) — bail on the program, or just pop back to the previous dialog, depending on where you are. context is everything 💅
hard-quit (default key: Shift + Q) — quit with zero confirmation. no "are you sure", no nothing. bye 👋
reload (default key: R) — reload the feed you're currently on.
reload-all (default key: Shift + R) — reload every feed. all of them. go get a snack while it runs 🍓
mark-feed-read (default key: Shift + A) — mark every article in the currently selected feed as read.
mark-all-feeds-read (default key: Shift + C) — mark articles in all feeds read. inbox zero energy, but for feeds 👑
mark-all-above-as-read (default key: n/a) — mark everything above the current spot 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 the next list entry.
prev (default key: Shift + K) — jump to the previous list entry.
random-unread (default key: Ctrl + K) — jump to a random unread article. chaos mode, lowkey iconic 🎲
open-in-browser (default key: O) — use the browser to open the URL tied to the current article, feed, or entry in the URL view.
open-in-browser-noninteractively (default key: n/a) — same idea as open-in-browser: use the browser to open the URL tied to the current article, feed, or entry in the URL view. BUT — and this is the whole point — the output of the browser (stdout and stderr) is not shown, and the browser doesn't receive keyboard input. you'd probably wanna add & at the end of the browser command to shove it into the background, too. ghost mode 🫥
open-in-browser-and-mark-read (default key: Shift + O) — use the browser to open the URL tied to the current article, or entry in the URL view. when you use it in the article list, it also marks the article as read. multitasking queen 💅
open-all-unread-in-browser (default key: n/a) — open every unread URL in the current feed. browser tabs go brrr 🌈
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) — flip between the HTML view and the source view in the article view.
toggle-article-read (default key: Shift + N) — toggle the read flag on the currently selected article, and clear the delete flag if it's set.
toggle-show-read-feeds (default key: L) — toggle whether read feeds show up in the feed list at all.
show-urls (default key: U) — show every URL in the article in a list (basically the urlview vibe).
clear-tag (default key: Ctrl + T) — clear the current tag.
set-tag (default key: T) — pick a tag.
open-search (default key: /) — open the search dialog. when you search from the article list, the search only applies to the articles of the current feed; otherwise it applies to all articles.
goto-url (default key: #) — open the URL dialog, then open whatever URL you typed 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. yes, zero is the tenth one, don't ask 💀
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 one's found) to the podcast download queue. peep the PODCAST SUPPORT section for the deets 🎧
edit-urls (default key: Shift + E) — edit the list of subscribed URLs. if a command is specified, Newsboat replaces the placeholders and then runs the command. Newsboat supports these placeholders in the command: %f (path to urls file), %L (line number of the current feed — or the 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 starts the editor configured through the VISUAL environment variable (if that's unset, EDITOR is used; fallback: vi). when editing finishes, Newsboat reloads the URLs file. example config:

bind E feedlist,articlelist,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. when it's looking glitchy, hit it ✨
cmdline (default key: :) — open the command line with an 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 the filter that's currently set.
bookmark (default key: Ctrl + B) — bookmark the currently selected article or URL.
edit-flags (default key: Ctrl + E) — edit the flags on the currently selected article.
next-unread-feed (default key: Ctrl + N) — go to the next feed that has unread articles. this one only works from the article list.
prev-unread-feed (default key: Ctrl + P) — go to the previous feed that has unread articles. also only works from the article list.
next-feed (default key: J) — go to the next feed. only works from the article list.
prev-feed (default key: K) — go to the previous feed. 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. ⚠️ careful bestie, and read this next bit properly: the articlelist might contain only a subset of a feed's articles (because of filters, or because show-read-articles is no), or it might contain a mix of articles from different feeds (if you're looking at a query feed) — either way, delete-all-articles affects just those articles, not all articles of the respective feed(s). it does what it says, not what you assumed 😭
purge-deleted (default key: $) — purge all articles marked as deleted from the article list. gone gone, no takebacks 💀
view-dialogs (default key: V) — view the list of open dialogs.
close-dialog (default key: Ctrl + X) — close the currently selected dialog.
next-dialog (default key: Ctrl + V) — go to the next dialog.
prev-dialog (default key: Ctrl + G) — go to the previous dialog.
pipe-to (default key: |) — pipe the article to a command. the text gets 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, but reversed. the remix 🔄
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: ,) — start macro execution. the next key you press picks the actual macro and runs it. ✨
switch-focus (default key: TAB) — switch focus between widgets. right now this only applies to the filebrowser and dirbrowser contexts.
goto-title (default key: n/a) — go to the item whose title contains the string you specify (case-insensitive).
prevsearchresults (default key: Z) — go back to the previous search results, if there were any. this one only works from searchresultslist.
article-feed (default key: n/a) — go to the feed of the currently selected article.

🌸 FORMAT STRINGS 🌸

so Newsboat has this genuinely powerful format string system, and it exists so you can configure how all sorts of stuff looks — like how entries show up in the feed list, or in the article list. customisation queen behaviour 👑

format strings are similar to the ones you'd find in the printf function in the C programming language. a format sequence starts with the % character, then comes the optional alignment indication: positive numbers mean the text inserted for that sequence gets padded on the left to a total width given by that number, while negative numbers mean padding on the right. after the padding indication comes the actual sequence identifier, which is usually a single letter. %=[width][identifier] centers the sequence — and if w=0, the whole width of the window gets used. 🎀

on top of that, Newsboat gives you other, more powerful sequences, like %>[char], which says the text to the right of the sequence gets aligned right on the screen, and the characters between the text on the left and the text on the right get filled in with [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] gets evaluated and inserted; otherwise [format 2] gets evaluated and inserted. the & and [format 2] are optional, i.e. if the identifier's text is empty, then an empty string gets inserted. 💅

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

💖 Table 1 — Available Identifiers for `feedlist-format` 💖

bestie these are the little letters you drop into your feedlist format string, and each one pulls a different lil fact about your feed. pick your faves:

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 🗂️

okay so while a reload-all operation is running, that download status is literally narrating what's happening to each feed, and it can be:

"to be downloaded" — shown as _ ⏳
"currently downloading" — shown as . 🌀
successfully downloaded — shown as (a space, yes really, she's quiet) ✅
"download error" — shown as x 💀

🦋 Table 2 — Available Identifiers for `articlelist-format` 🦋

now for the article list, your format string options go feral (affectionate):

a — Article author ✍️
D — Publication date. and bestie, this can be tweaked further with datetime-format 📅
f — Two characters, okay listen: 1) "N" if article is unread, "D" if article is deleted, a space otherwise; 2) "!" if article has flags, a space otherwise. two whole moods in two chars 💅
n — "unread" field 👀
d — "deleted" field 🗑️
F — Article flags 🚩
i — Article index 🔢
t — Article title 🏷️
T — If the article list displays articles from different feeds, then this identifier 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` 🌸

tag picker screen? she's got her own identifiers, and she's serving:

i — Line's index in the list 🔢
T — The tag this line corresponds to 🏷️
f — Number of unread feeds under 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` ✨

and for your notifications, the little pop-up moment, here's what you can reference:

n — Number of unread articles 📰
f — Number of unread feeds 📬
d — Number of new unread articles (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` 🎧

okay so when you're formatting your podcast list, these are the lil letters you can drop in. each one is a whole vibe:

i — the download index 🫶
d — how much you've currently downloaded, in megabytes, and it shows one digit of precision ✨
t — the total download size, in megabytes, also with one digit of precision 💖
p — the percentage you've downloaded, one digit of precision 🎀
k — the download speed, two digits of precision, always in KB/s. note bestie: it does not include the "KB/s" text, so don't go looking for it 💅
K — the download speed, two digits of precision, but human readable this time — it automatically switches between KB/s, MB/s and GB/s 🌈
S — the status of the download. it'll be one of these: "queued", "downloading", "ready", "canceled", "deleted", "missing", "played", "finished" or "failed" 👑
u — the url of the download 🔗
F — the absolute filename of the download, from the root directory. like, ~/downloads/podcast.mp3 → /home/name/downloads/podcast.mp3 🦋
b — the basename of the download. like, /home/name/downloads/podcast.mp3 → podcast.mp3 🌸

📋 Table 6 — Available Identifiers for `download-path` and `download-filename-format` 💾

these ones are for naming your files and folders. lowkey the most useful set fr fr:

u — the filename part of the download URL. it may be empty. it may also include a query string (https://en.wikipedia.org/wiki/Query_string) 🙈
n — the name of the podcast feed 🌟
N — the name of the podcast feed, but it keeps the original feed's name, even when you selected it through a query feed. iconic 🎀
h — the name of the podcast feed's hostname 🖥️
t — the title of the podcast episode 💜
e — the extension of the podcast episode 📎
F — the publication date of the podcast episode, formatted as yyyy-mm-dd 🗓️
m — the month when the podcast episode was published 🌙
b — the abbreviated month name when the podcast episode was published 🌸
d — the day when the podcast episode was published ☀️
H — the hour when the podcast episode was published 🕐
M — the minute when the podcast episode was published 🕜
S — the second when the podcast episode was published 🕰️
y — the year when the podcast episode was published, formatted as yy ⭐
Y — the year when the podcast episode was published, formatted as yyyy ✨

🌟 Examples 🌟

steal these, they're literally right here:

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"

ok wait, that %% in the podlist one? that's the literal percent sign, not a format code. don't let it jumpscare you bestie 💖

💅 DIALOG TITLES 💅

okay so bestie, you can customize the title format of literally every dialog in Newsboat 🎀 Here's the full rundown: each dialog, the config variable that controls its title, and what it defaults to. And a lil list of the format identifiers so you actually know what those % things mean.

heads up tho 🫶 the title formats are localized — so if you're running a different locale that Newsboat supports, the actual title text you see might be different unless you customize it yourself. iykyk.

Table 7. Dialog Title Formats ✨

Feed List — config variable: feedlist-title-format — default: %N %V - %?F?Feeds&Your feeds? (%u unread, %t total)%?F? matching filter '%F'&?%?T? - tag '%T'&?
Article List — config variable: articlelist-title-format — default: %N %V - Articles in feed '%T' (%u unread, %t total)%?F? matching filter '%F'&? - %U
Search Result — config variable: searchresult-title-format — default: %N %V - Search results for '%s' (%u unread, %t total)%?F? matching filter '%F'&?
File Browser — config variable: filebrowser-title-format — default: %N %V - %?O?Open File&Save File? - %f
Directory Browser — config variable: dirbrowser-title-format — default: %N %V - %?O?Open Directory&Save File? - %f
Help — config variable: help-title-format — default: %N %V - Help
Select Tag Dialog — config variable: selecttag-title-format — default: %N %V - Select Tag
Select Filter Dialog — config variable: selectfilter-title-format — default: %N %V - Select Filter
Article View — config variable: itemview-title-format — default: %N %V - Article '%T' (%u unread, %t total)
URL View — config variable: urlview-title-format — default: %N %V - URLs
Dialog List — config variable: dialogs-title-format — default: %N %V - Dialogs

Table 8. Common Title Format Identifiers 🌈

these two show up in like every title format, so memorize them fr fr:

N — Name of the program, i.e. "Newsboat" 👑
V — Program version ⭐

🌸 Table 9. Feed List Title Format Identifiers 🌸

T — the tag you've currently got selected (and it's just empty if you haven't picked one, no biggie)
t — how many feeds there are in total
u — how many of those feeds are unread
U — how many articles are unread
F — the filter expression that's active right now (empty when no filter is active)

🎀 Table 10. Article List Title Format Identifiers 🎀

T — the feed's title
U — the feed's URL
u — number of unread articles
t — number of total articles
F — the filter expression currently in play (empty if no filter is active)

🔍 Table 11. Search Result Title Format Identifiers 🔍

s — the search phrase
… — plus literally all the identifiers supported by articlelist-title-format (peep the table right above this one, bestie)

📁 Table 12. File Browser Title Format Identifiers 📁

f — the current path
O — non-empty when the file browser is in open mode, empty when it's in save mode

🗂️ Table 13. Directory Browser Title Format Identifiers 🗂️

f — the current path
O — non-empty when the directory browser is in open mode, empty when it's in save mode

📰 Table 14. Article View Title Format Identifiers 📰

T — the article's title
F — the feed's title
u — number of unread articles
t — number of total articles

✨ TAGGING ✨

okay so this is one of my fave features fr. Newsboat lets you categorize your RSS feeds — or "tag" them, as we say around here 💅. Every single RSS feed can have 0 or more tags attached to it. Then, inside Newsboat, you can choose to only show the feeds that match a certain tag. It's giving flexible. It's giving powerful. It's giving your feeds finally organized the way they deserve 👑

Usually your urls file has one RSS feed URL per line. To give a feed a tag, you just stick it on as a single word, separated by blanks like a space or a tab. If your tag needs to have spaces in it, you must wrap it in quotes (") — peep the example below. A urls file could lowkey 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

So now when you launch Newsboat with this config, you can hit T to pick a tag. Pick the news tag and boom — all three RSS feeds show up. Hit T again and select the conspiracy tag and you'll only see the https://blog.fefe.de/rss.xml?html RSS feed. And when you press Ctrl + T, that clears the current tag and shows you all the RSS feeds again, no matter what tags they've got. periodt.

A special type of tag is the ones that start with the tilde character (~) 🌈. When Newsboat finds one of those, the feed title gets set to the tag name (minus the ~ character itself). These tags get ignored whenever any kind of "first tag" property is used. So with this feature you can give your feeds literally any title you want in your feed list:

https://rss.orf.at/news.xml "~ORF News"

Another special type is tags that start with the exclamation mark (!) 😱. When Newsboat finds one of those, the feed gets 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 show up in the feedlist at all — but their articles are still fully reachable through the query feed titled News from around the globe. And the "hidden" tags in this example don't even have names, because their only job is hiding the feed they're tagging. sneaky iconic behavior tbh 🫶

🌸 SCRIPTS AND FILTERS 🌸

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

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

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

exec:~/bin/execurl-script
filter:~/bin/filter-script:https://some.test/url

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

"exec:~/bin/execurl-script param1 param2"

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

"filter:~/bin/filter-script param1 param2:https://url/foobar"

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

exec:~/bin/execurl-script tag1 tag2 "quoted tag"
filter:~/bin/filter-script:https://some.test/url tag3 tag4 tag5

If you need to write your own extension, see this short guide <https://web.archive.org/web/20090724045314/http://kiza.kcore.de/software/snownews/snowscripts/writing> 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/examples 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 traditionally called a "killfile", i.e. based on the content of this "killfile", articles that match certain conditions do not get displayed and are not presented to the user at all. 🙈

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

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 extended regular expression <https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/V1_chap09.html>, which will be matched case-insensitive.
"*" to match any feed (asterisk is not a pattern, glob or regex—we simply reserve it to mean "all feeds").

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

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

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 ignore mode saves some storage, you cannot simply "undo" the ignore by removing it from the configuration file: if an ignored article has already vanished from a feed, it won't reappear. On the other hand, the display ignore mode requires some more space, but has the advantage that an ignore can be "undone" by removing the ignore-article configuration command from the configuration. 😭

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

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 external media player is needed for playback. This support differs a bit from other podcast aggregators or "podcatchers" in how it is done. 👑

Podcast content is transported in RSS feeds via special tags called "enclosures". Newsboat recognizes these enclosures and stores the relevant information for every podcast item it finds in an RSS feed. Since version 2.0, it also recognizes and handles the Yahoo Media RSS extensions. 🌈

Remote APIs don't always list those "enclosures", so podcasts might be missing from Newsboat. Such APIs are marked in the relevant section of our docs. If a note is missing but you still don't see enclosures in Newsboat, please file an issue and we'll get to the bottom of it! 🫶

💻 COMMAND LINE 💻

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

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

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

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

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

Currently, the following command line commands are available:

quit — 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 & directly 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 alternative 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 💖

okay so by default Newsboat is a classic Unix girly and keeps everything in a "dotdir" at ~/.newsboat. very traditional, very demure. but she ALSO supports the modern way — the XDG Base Directory Specification — which splits your files between these two spots:

$XDG_CONFIG_HOME/newsboat/ (and XDG_CONFIG_HOME defaults to ~/.config)
$XDG_DATA_HOME/newsboat/ (and XDG_DATA_HOME defaults to ~/.local/share)

here's the vibe check: if the newsboat directory exists under XDG_CONFIG_HOME, then Newsboat will use the XDG directories (and it'll create the data directory if it needs to). otherwise? Newsboat just defaults to ~/.newsboat. simple as that ✨

if you're currently living in ~/.newsboat/ but you wanna migrate to XDG directories, move your files like this:

config, urls — move these to $XDG_CONFIG_HOME/newsboat/
cache.db, history.search, history.cmdline, queue — move these to $XDG_DATA_HOME/newsboat/

Newsboat and Podboat also create "lock files" 🔒 and no bestie, they're not being possessive, they're protecting you. these stop you from starting two instances of the same program, which would absolutely corrupt your data (not the cute kind of chaos). Newsboat and Podboat remove these files when you quit the program, so there's genuinely no need to copy them anywhere — just be aware of them in case you write scripts that work with cache.db or queue. by default, the lock files live here:

Newsboat in dotdir: ~/.newsboat/cache.db.lock
Newsboat in XDG: $XDG_DATA_HOME/newsboat/cache.db.lock
Podboat in dotdir: ~/.newsboat/pb-lock.pid
Podboat in XDG: $XDG_DATA_HOME/newsboat/.lock

Newsboat places the lock file right next to the cache file, so if you use the cache-file setting or pass the --cache-file command-line argument, the path to the lock file changes too. Podboat's lock can be placed somewhere else entirely using the --lock-file command-line argument. iconic, honestly 💅

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. she's got a fallback plan, always 💜

🌸 ENVIRONMENT 🌸

these are the little environment variables that whisper sweet nothings to Newsboat and tell her how to behave:

BROWSER — tells Newsboat what browser to use if there's no browser setting in the config file. if this variable doesn't exist, a default of lynx(1) will be used. yes, lynx. retro queen 👑
CURL_CA_BUNDLE — tells Newsboat to use the specified certificate file to verify the peer. the file may contain multiple certificates, and the certificate(s) must be in PEM format.

this option is useful if your libcurl is built without useful certificate information, and you can't rebuild the library yourself. we've all been there 😭

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.example.com. domain names that start with a dot only match subdomains, e.g. .example.com matches bar.example.com but not example.com itself. sneaky little dot, we love her.

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. fr fr, she said string matching and she MEANT it 💀

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 environment 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

and that's the whole page, bestie!! we did it 🫶 this is from the NEWSBOAT(1) manual page, dated 2026-10-05, and you can find it in the source/version info at the bottom of the page. go forth and subscribe to way too many feeds, that's your main character era ✨🦋💖

📦 where this page comes from

fedora 43: newsboat 2.45-1.fc43 · MIT
fedora 44: newsboat 2.45-1.fc44 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-19: a language model's rewrite of the original, under its terms

NEWSBOAT(1)

💖 NEWSBOAT(1) 💖

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

✨ OPTIONS ✨

🌈 FIRST STEPS 🌈

🎀 Adding Feeds 🎀

🌸 First UI Interaction 🌸

🌟 CONFIGURATION 🌟

🌈 Example 🌈

✂️ Splitting long lines into multiple ones ✂️

✨ Using Double Quotes ✨

✨ Shell Evaluation ✨

✨ Escaping ✨

✨ Key Bindings ✨

💖 Key Sequence

💖 Dialog

💖 Operation List

✨ Old Style Key Bindings ✨

💖 Key

💖 Operation

💖 Dialog

✨ Colors ✨

✨ CONFIGURATION COMMANDS ✨

✨ AVAILABLE OPERATIONS ✨

🌸 FORMAT STRINGS 🌸

💖 Table 1 — Available Identifiers for feedlist-format 💖

🦋 Table 2 — Available Identifiers for articlelist-format 🦋

🌸 Table 3 — Available Identifiers for selecttag-format 🌸

✨ Table 4 — Available Identifiers for notify-format ✨

📋 Table 5 — Available Identifiers for podlist-format 🎧

📋 Table 6 — Available Identifiers for download-path and download-filename-format 💾

🌟 Examples 🌟

💅 DIALOG TITLES 💅

🌸 Table 9. Feed List Title Format Identifiers 🌸

🎀 Table 10. Article List Title Format Identifiers 🎀

🔍 Table 11. Search Result Title Format Identifiers 🔍

📁 Table 12. File Browser Title Format Identifiers 📁

🗂️ Table 13. Directory Browser Title Format Identifiers 🗂️

📰 Table 14. Article View Title Format Identifiers 📰

✨ TAGGING ✨

🌸 SCRIPTS AND FILTERS 🌸

💀 KILLFILES 💀

🎧 PODCAST SUPPORT 🎧

💻 COMMAND LINE 💻

📁 FILES 💖

dotfiles 🎀

XDG 🌈

🌸 ENVIRONMENT 🌸

👀 SEE ALSO

👑 AUTHOR

💖 Table 1 — Available Identifiers for `feedlist-format` 💖

🦋 Table 2 — Available Identifiers for `articlelist-format` 🦋

🌸 Table 3 — Available Identifiers for `selecttag-format` 🌸

✨ Table 4 — Available Identifiers for `notify-format` ✨

📋 Table 5 — Available Identifiers for `podlist-format` 🎧

📋 Table 6 — Available Identifiers for `download-path` and `download-filename-format` 💾