NEWSRAFT(1) General Commands Manual NEWSRAFT(1)

newsraft - feed reader for terminal

newsraft [-f FILE1] [-c FILE2] [-d FILE3] [-l FILE4] [-p] [-v] [-h]

Newsraft is a small text based program for reading syndication feeds - it enables you to obtain content from many blogs and platforms and view all this via one single interface in an efficient and streamlined manner.

-f FILE

Force use of FILE as feeds file.

-c FILE

Force use of FILE as config file.

-d FILE

Force use of FILE as database file.

-l FILE

Write log information to FILE.

-p

Purge feeds not specified in the feeds file.

-v

Print version information.

-h

Print usage information.

To start using Newsraft you have to create a feeds file with the list of links that point to feeds you want to receive news from. Format of this file and valid paths for the location of this file are discussed in the FEEDS FILE section.

When your feeds file is ready, you can launch Newsraft. Navigation in the interface is carried out by the same keys as in the vi(1) text editor. There are only 4 menus you're gonna deal with: sections menu, feeds menu, items menu and pager menu.

Sections menu consists of section entries which are needed to organize feeds in groups to be able to process them in bulk. They are kind of directories for feeds. If you didn't specify any section declarations in your feeds file then you will get to the feeds menu straightaway.

Feeds menu consists of feed entries. Every feed entry contains news downloaded from one specific source which you have set in feeds file. To update a single feed you have to select it and press r. If you want to update all feeds, Ctrl-R (or ^R for short) will do this fine. From feeds menu you can get to the items menu by entering some feed.

Items menu consists of feed item entries (i. e. single pieces of news) which you get when you update feeds in the previous menu. Every feed item entry has two switchable properties - read state and importance state. Keys to force read state change: d to mark read, D to mark unread, ^D to mark everything read. Keys to force importance state change: i to mark important, I to mark unimportant. To view item's content you have to go to pager menu by entering selected item.

Pager menu will display some details about selected item and render its content if it was provided by feed. Usually feed item entries have a links section with one link pointing to a related web page and several links that were mentioned in the item's content. You can copy these links into your clipboard with y key and open them in your web browser with o key. To target a key action to link with a specific index you have to prefix your key with this index. For example, 5y will copy fifth link and 17o will open seventeenth link in the web browser. You can also setup custom command bindings to execute any commands with these links. Consider this config file:

bind m exec mpv "%l"
bind f exec feh "%l"

With this you will be able to open any link in mpv(1) and feh(1) directly from your terminal! Isn't it awesome? It is freaking amazing!

For both sections menu and feeds menu there is a special view mode - explore mode. You can toggle this mode by pressing the e key in either sections menu or feeds menu. What it does is truly miraculous - it lists all the feed item entries in the current scope (i. e. explore mode in sections menu will show you all the feed item entries in the database, while in feeds menu it will show you all the feed item entries of feeds in the current feeds menu). This mode may come in handy when you want to quickly scroll through all the news without switching between sections and feeds back and forth.

And for dessert, I'll tell you about search functionality. You can type / in items menu to start search input - enter the desired query here and press Enter. This will generate a new list of items based on given search query. To return to the original items list, you just need to make an empty search (press / and Enter in sequence). Searching like that in sections menu and feeds menu will automatically enable explore mode and apply your search query.

This file contains feed entries that Newsraft will display and process. There are 3 types of lines in feeds file.

Feed lines start with a URL. After at least one whitespace character, the name of the feed may be specified - it must be enclosed in double quotes. For example:

https://example.org/feed.xml "Lorem Ipsum Blog"

Section lines start with @ character. After any number of whitespace characters, the name of the section must be specified. For example:

@ Software Releases

Comment lines start with # character. These lines are completely ignored. For example:

# Look closely. The beautiful may be small.

Both feed and section lines allow you to set an auto update timer at the end, which will force section or feed related to this line to be automatically updated at a certain frequency. The period of automatic updates is specified in minutes and must be enclosed in square brackets. If you set an auto update timer for a feed that belongs to a section with an auto update timer set, then the auto update timer of the feed will take precedence. Auto update timer of 0 disables automatic updates. Let's walk through a small example and see how it all works. Consider this feeds file:

http://example.org/feed1.xml
http://example.org/feed2.xml [30]

@ Replies [20]
http://example.org/feed3.xml [10]
http://example.org/feed4.xml "Forum notifications"

@ News [60]
http://example.org/feed5.xml
http://example.org/feed6.xml "Local weather" [0]

In this example, feed1 will never update automatically, feed2 will update every 30 minutes, feed3 will update every 10 minutes, feed4 will update every 20 minutes, feed5 will update every 60 minutes and feed6 will never update automatically.

If you just want to automatically update all feeds then you should set an auto update timer for Global section, but before doing so, think about what load can be exerted on a servers by frequent downloads from a large number of users. Going for a small auto update timer on Global section will most likely result in a waste of a lot of resources. You have been warned.

Search precedence:

1.$XDG_CONFIG_HOME/newsraft/feeds
2.$HOME/.config/newsraft/feeds
3.$HOME/.newsraft/feeds

This file is used to override default settings and bindings of Newsraft. Presence of config file is totally optional and Newsraft will work without it just fine. There are 3 types of lines in config file.

Setting lines start with the set word. You can find available settings in the SETTINGS and COLOR SETTINGS sections. Format of these lines is as follows, where value can be enclosed in single or double quotes:

set setting value

Binding lines start with the bind word. They define actions that are performed when certain keys are pressed. Complete list of assigned actions can be found in the ACTIONS section. Format of these lines is as follows:

bind key action

There is also a way to assign command bindings. When a key with assigned command binding is pressed, the specifiers in the command are replaced with values of the corresponding entry and the command is executed. You can find which specifiers are available in the description of the menu-item-entry-format setting. Format of these lines is as follows:

bind key exec command

Binding lines support assigning multiple actions to one key. Assigned actions must be separated with semicolon symbols, for example:

bind key action1; action2; exec command1; exec command2; action5

In case you want to disable some binding which was set in Newsraft by default, you can use a line according to this format:

unbind key

Comment lines start with # character. These lines are completely ignored. For example:

# Good design is as little design as possible.

Search precedence:

1.$XDG_CONFIG_HOME/newsraft/config
2.$HOME/.config/newsraft/config
3.$HOME/.newsraft/config

This file stores everything you download from feeds in sqlite3(1) format. Although you now know the format in which the data is stored, it is highly recommended to avoid modifying the database manually - things will break and it will be very sad.

Search precedence:

1.$XDG_DATA_HOME/newsraft/newsraft.sqlite3
2.$HOME/.local/share/newsraft/newsraft.sqlite3
3.$HOME/.newsraft/newsraft.sqlite3

scrolloff (default: 0)

Minimal number of list menu entries to keep above and below the selected entry. If you set it to a very large value the selected entry will always be in the middle of the list menu (except for start and end of the list menu).

items-count-limit (default: 0)

Maximum number of items stored in one feed. Zero disables the limit.

update-threads-count (default: 0)

Maximum number of update processes running simultaneously. If set to zero, value of the setting is set to the number of CPU cores available. You may want to set this setting to a lower value in cases of a slow network connection where parallel downloads can slow down the update process. If set to a value greater than the number of CPU cores available, it will be implicitly reduced to the number of CPU cores to avoid performance issues.

open-in-browser-command (default: ${BROWSER:-xdg-open} "%l")

Shell command for opening URL in a web browser. The URL to be opened is put in place where %l specifier is located.

copy-to-clipboard-command (default: auto)

Shell command for copying text to clipboard. All copied data is sent to the standard input of the command. If it is set to "auto", then Newsraft will set the setting value depending on the environment variables: "wl-copy" command will be set if environment variable WAYLAND_DISPLAY is present and "xclip -selection clipboard" command will be set if environment variable DISPLAY is present, otherwise "false" command will be set.

proxy (default: "")

Sets the proxy to use for the network requests. It must be either a hostname or dotted numerical IPv4 address. To specify IPv6 address you have to enclose it within square brackets. Port number can be set by appending :PORT to the end of setting value. By default proxy protocol is considered HTTP, but you can set a different one by prepending SCHEME:// to the setting value.

proxy-user (default: "")

User for authentication with the proxy server.

proxy-password (default: "")

Password for authentication with the proxy server.

global-section-name (default: Global)

Name of the section that contains all feeds.

item-formation-order (default: feed,title,authors,date,max-content)

Sets the order in which the data of item entry is formed for viewing in a pager. Possible fields are: feed, title, link, date, authors, contributors, editors and max-content.

content-date-format (default: %a, %d %b %Y %H:%M:%S %z)

Date format in the content view. Specifier values correspond to the strftime(3) format.

list-entry-date-format (default: %b %d)

Date format of the list entries. Specifier values correspond to the strftime(3) format.

menu-section-entry-format (default: %5.0u @ %t)

Format of the section list entries. Specifiers are as follows:
n index number;
u unread items count;
t section title.

menu-feed-entry-format (default: %5.0u │ %o)

Format of the feed list entries. Specifiers are as follows:
n index number;
u unread items count;
l feed link;
t feed title;
o feed title if set, feed link otherwise.

menu-item-entry-format (default: " %u │ %d │ %o")

Format of the item list entries. Specifiers are as follows:
n index number;
u "N" if item is unread, " " otherwise;
d update date formatted according to list-entry-date-format;
D publication date formatted according to list-entry-date-format;
l item link;
t item title;
o item title if set, item link otherwise;
L feed link;
T feed title;
O feed title if set, feed link otherwise.

menu-explore-item-entry-format (default: " %u │ %d │ %-28O │ %o")

Format of the item list entries in explore mode. Specifiers are the same as in menu-item-entry-format.

sections-menu-paramount-explore (default: false)

Enables explore mode in sections menu by default.

feeds-menu-paramount-explore (default: false)

Enables explore mode in feeds menu by default.

initial-unread-first-sorting (default: false)

Enables unread first sorting in items menu by default.

mark-item-read-on-hover (default: false)

Mark every item that gets selected as read.

analyze-database-on-startup (default: true)

Run "ANALYZE" SQLite command on the database every time you start Newsraft. It gathers statistics about database and uses it to optimize some queries making runtime faster.

clean-database-on-startup (default: false)

Run "VACUUM" SQLite command on the database every time you start Newsraft. It rebuilds the database file by packing it into a minimal amount of disk space. This can significantly increase startup time.

download-timeout (default: 10)

Maximum time in seconds that you allow Newsraft to download one feed. Zero disables the limit.

download-speed-limit (default: 0)

Maximum download speed in kilobytes per second (kB/s). Zero disables the limit.

status-messages-count-limit (default: 1000)

Maximum number of status messages stored in memory. If set to zero, status messages history won't be stored in memory.

send-user-agent-header (default: true)

Attach user-agent header to download requests. See user-agent setting.

user-agent (default: auto)

User-agent string to attach to download requests. If it is set to "auto", Newsraft will generate it according to the following format:

"newsraft/" + NEWSRAFT_VERSION + " (" + OS_NAME + ")"

OS_NAME shouldn't be a matter of privacy concern, because on most systems it contains nothing more like "Linux" or "Darwin". If you want to be sure of this, check Newsraft log to see how user-agent is set at startup.

respect-ttl-element (default: true)

Prevents too frequent updates for some feeds. The limit is set by the creators of the feeds in order to save traffic and resources for a very rarely updated feeds. Disabling it is strongly discouraged.

respect-expires-header (default: true)

Prevents feed updates until the expiration date of the previously downloaded information in order to save traffic and resources. Disabling it is strongly discouraged.

send-if-none-match-header (default: true)

Sends an entity tag corresponding to the previously downloaded information. If the server from which the feed is downloaded contains information with the same tag, then in order to save traffic and resources, it will reject the download request. Disabling it is strongly discouraged.

send-if-modified-since-header (default: true)

Sends a date corresponding to the last modification of previously downloaded information. If the server from which the feed is downloaded contains information with the same modification date, then in order to save traffic and resources, it will reject the download request. Disabling it is strongly discouraged.

Color settings are the same settings as above, but they take a certain set of whitespace separated tokens for their values: one hue word and optional format attributes. Available tokens for hue are default, black, red, green, yellow, blue, magenta, cyan and white. Available tokens for format attributes are bold, italic and underlined.

color-status-good-fg (default: green)

Text color of status area when reporting success.

color-status-good-bg (default: default)

Background color of status area when reporting success.

color-status-info-fg (default: cyan)

Text color of status area when reporting information.

color-status-info-bg (default: default)

Background color of status area when reporting information.

color-status-fail-fg (default: red)

Text color of status area when reporting failure.

color-status-fail-bg (default: default)

Background color of status area when reporting failure.

color-list-item-fg (default: default)

Text color of item list entry.

color-list-item-bg (default: default)

Background color of item list entry.

color-list-item-unread-fg (default: yellow)

Text color of unread item list entry.

color-list-item-unread-bg (default: default)

Background color of unread item list entry.

color-list-item-important-fg (default: magenta)

Text color of important item list entry.

color-list-item-important-bg (default: default)

Background color of important item list entry.

color-list-feed-fg (default: default)

Text color of feed list entry.

color-list-feed-bg (default: default)

Background color of feed list entry.

color-list-feed-unread-fg (default: yellow)

Text color of unread feed list entry.

color-list-feed-unread-bg (default: default)

Background color of unread feed list entry.

color-list-section-fg (default: default)

Text color of section list entry.

color-list-section-bg (default: default)

Background color of section list entry.

color-list-section-unread-fg (default: yellow)

Text color of unread section list entry.

color-list-section-unread-bg (default: default)

Background color of unread section list entry.

Keys Actions
j, KEY_DOWN select-next
k, KEY_UP select-prev
space, ^F, KEY_NPAGE select-next-page
^B, KEY_PPAGE select-prev-page
g, KEY_HOME select-first
G, KEY_END select-last
J jump-to-next
K jump-to-prev
n jump-to-next-unread
N jump-to-prev-unread
p jump-to-next-important
P jump-to-prev-important
s sorting-method-next
S sorting-method-prev
u toggle-unread-first-sorting
l, ^J, KEY_RIGHT, KEY_ENTER enter
r reload
^R reload-all
d mark-read; jump-to-next
D mark-unread; jump-to-next
^D mark-read-all
(not set) mark-unread-all
i mark-important
I mark-unimportant
e toggle-explore-mode
v status-history-menu
o open-in-browser
y, c copy-to-clipboard
/ start-search-input
h, ^?, KEY_LEFT, KEY_BACKSPACE navigate-back
q quit
Q quit-hard

Data formats of feeds which Newsraft recognizes. Not the whole functionality of these formats is implemented, but only the functionality that is most likely to carry the most essential information.

RSS 2.0, 1.1, 1.0, 0.94, 0.93, 0.92, 0.91, 0.9
Atom 1.0
RSS Content Module
Media RSS
DublinCore 1.1 Elements
JSON Feed

Newsraft's behavior depends on the environment variables set, however not all environment variables affect Newsraft directly - many environment variables affect libraries that Newsraft is built on. Thus, ncurses(3) and libcurl(3) recognize a large number of different environment variables which you can learn more about on ncurses(3) and libcurl-env(3) respectively.

However, there is one significant ncurses(3) environment variable that is worth mentioning here - ESCDELAY. It sets delay for reading Escape key. It may surprise you that its default value is 1000 ms, which is well explained in ncurses(3), but many may prefer a value much less than that or even 0.

Directory for applications to store their configuration.

Directory for applications to store their data.

Home directory of your user.

Web browser of your user.

Identifier of the Wayland graphics display.

Identifier of the X graphics display.

Setting that forcibly makes the interface monochrome when set.

vi(1), mpv(1), feh(1), sqlite3(1), strftime(3), ncurses(3), libcurl(3), libcurl-env(3)

Don't be ridiculous...

Grigory Kirillov <txgk@bk.ru>

2023-10-02