Feed Commas - user-friendly console CommaFeed client.
1. Introduction
Feed Commas is a client application for CommaFeed, a Google Reader inspired self-hosted RSS reader. You don’t have to host your own instance of CommaFeed to use it. Free (gratis) accounts are available on https://commafeed.com and they work with Feed Commas as well.
Feed Commas is terminal application, but with a catchy, curses-based graphical frontend. It’s mainly navigated from keyboard; by default it is configured with vi-like keybindings, but you can reconfigure it anyway you like. It’s intended audience are ordinary users who are not afraid of launching a console.
2. Installation
The easiest way to install Feed Commas is to use pip:
$ pip install --user feedcommas
If you downloaded Feed Commas source code directly, you can still easily install it quite easily by creating a developement virtualenv and symlinking Feed Commas executable. This method has additional benefit that pulling latest changes from git will auto-update your installation (unless dependencies change).
To use this method, you need installed python3-tox
package:
$ cd feedcommas-git $ tox -e dev $ ln -s $(pwd)/.tox/dev/bin/feed-commas $HOME/.local/bin/feed-commas
2.1. Dependencies
Package | Version |
---|---|
|
>= 3.4 |
|
>= 1.3.1 |
|
>= 2.13.0 |
|
>= 4.5.3 |
|
>= 1.1.6 |
>= 0.1.0 |
Package | Version |
---|---|
|
|
|
|
|
3. Interface
3.1. First run
┌──────────────────────────────────────────────────────────────────────────────┐ │Log in to CommaFeed │ │ │ │Name or email: █ │ │Password command: │ │Password (plain text, optional): │ │ │ │ │ │ < Ok >< Cancel >│ └──────────────────────────────────────────────────────────────────────────────┘
On the first run , Feed Commas will ask you to fill credentials needed to login to CommaFeed. Above screen will be displayed. You can navigate it using Tab, Shift+Tab, and arrow buttons: ↑, ↓, ← and →.
You should enter either plain text password (which is discouraged) or password command, which should be a shell command returning a single line containing a password used to log in to your CommaFeed account.
To confirm credentials, either click < Ok >
button or press Enter. To
exit Feed Commas, click < Cancel >
button or press Esc.
Correct credentials are saved to your configuration file (see Configuration and server sections for details about that) and you are then presented Feed Commas main window.
A note about passwords
Plain text password is saved into If your password command returns several lines of text, you can use standard
Unix tools to filter it, because pass commafeed | head -1 Some commands return passwords terminated with a newline character: pass commafeed | head -1 | tr -d '\n' |
3.2. Main window
▼ Menu Article list ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │All │┌────────────────────────────────────────────────────┐│ │Starred ││How to make `lynx` fast? Tue Mar 7 10:52:00 2017││ │Daily read ││ ││ │ /r/commandline(1) ││ Anyone care share their lynx config? ││ │ Lorem ipsum ││ For some reason, lynx on my computer cannot open ││ │ The Codist ││websites instantly. ││ │ Andrzej's C++ blog ││ ││ │ Ludic Linux ││☐ submitted by /u/blablabla││ │Comics │└────────────────────────────────────────────────────┘│ │ MonkeyUser │┌────────────────────────────────────────────────────┐│ │ Geek&Poke ││Lorem ipsum Mon Mar 6 23:52:14 2017││ │ xkcd ││ ││ │ ││ Lorem ipsum dolor sit amet. ││ │ ││ ││ │ ││★☑ author││ │ │└────────────────────────────────────────────────────┘│ │[uo] │ │:show-unread │ └──────────────────────────────────────────────────────────────────────────────┘ ▲ Commandline / message display
Above is example view of Feed Commas, drawn to fit 80-characters-wide terminal. Interface resizes dynamically, so on modern displays you’ll encounter more free space.
Two main parts are: 1) menu with subscribed feeds and categories on the left, and 2) article list on the right.
Feed Commas starts with a focus on article list. To switch between menu and article list, use h and l. j and k navigates menu and scrolls article list. See navigation for details.
There’s also a command line on the bottom of the screen. It’s accessible by pressing : key. To close it, press Esc or delete all of the typed text. To show completion hints press Tab.
Above a commandline there’s a single line called status line. It displays several informations (like whether Feed Commas is in online/offline mode) and notifications and messages sent by Feed Commas to the user.
3.3. Commands
Most of the commands are bound to some key by default, but not all of them. All
of them, however, are available to be used via a commandline. All commands,
beside navigation ones (nav-up
, nav-down
, nav-right
and
nav-left
) are available. For a complete list, see keys
subsection.
You don’t have to type the whole command. If there’s only one command which
starts with a typed substring, a correct command will be executed. No command is
executed in case of ambiguity. For example, :q
will work the same as :quit
,
but :read
won’t run anything because there are two possible commands:
read-toggle
and read-all
.
4. Configuration
Feed Commas can be configured by setting options in a standard
ini-style configuration file. If not specified via -c,
--config
flag, configuration is searched in a filesystem in a way described by
XDG Base Directory Specification. In practice it means that for
most users it will be located in ~/.config/feed-commas/config.ini
. However,
any of below files can be read if previous ones were not found:
-
$XDG_CONFIG_HOME/feed-commas/config.ini
. If$XDG_CONFIG_HOME
is not set, it defaults to$HOME/.config
. -
any of
$XDG_DATA_DIRS/feed-commas/config.ini
.$XDG_DATA_DIRS
is colon-separated list of directories to check. If it is not set, it defaults to/etc/xdg
.
If configuration file is not found, Feed Commas will create one.
Before Feed Commas terminates, any changes to the configuration are written back.
Specific configuration files
You can tell Feed Commas to use a specific configuration file by using $ feed-commas -c ~/feedcommasrc |
4.1. Structure
INI files are made of sections. Each section contains a number of options. Below
is incomplete example of file which has [server]
and [keys]
sections.
[server] address = https://commafeed.com [keys] nav-up = k nav-down = j [settings] workers = 2
Server
[server]
contains options for configuring access to CommaFeed server.
Option | Default value | Description |
---|---|---|
|
|
Address of CommaFeed instance with which Feed Commas will communicate. |
|
name or e-mail used to login to CommaFeed instance. |
|
|
Plain text password which will be used to login to CommaFeed. Due to security reasons, it is not recommended to leave plain text passwords in any configuration file. Use password-cmd instead. |
|
|
A command used to get password to login to CommaFeed. It takes precedence over password, even if the latter is set. |
|
|
|
Time in seconds after which Feed Commas timeouts and goes to auto-offline mode. When in auto-offline mode, Feed Commas will retry connecting with Comma Feed, but meanwhile will use local cache of RSS entries. You can force Feed Commas to try to reconnect immediately by refreshing article list. |
Keys
[keys]
contains key mappings used in Feed Commas.
Option | Default value | Description |
---|---|---|
|
Navigates and scrolls up. It is used e.g. to navigate a menu and scroll article list. |
|
|
|
Navigates and scrolls down. It is used e.g. to navigate a menu and scroll article list. |
|
|
Navigates right. It is used e.g. to switch used panel from menu to article list. |
|
|
Navigates right. It is used e.g. to switch used panel from article list to menu. |
|
Toggles between read and unread state for currently selected article. |
|
|
|
Stars or unstars currently selected article. |
|
Marks all unread articles from currently displayed feed (or category with its descendants) as read. |
|
Shows both unread and read entries. Modifies show-read option. |
||
Shows only unread entries. Modifies show-read option. |
||
|
Instantly refreshes list of articles. |
|
|
Downloads articles for offline read, up to the sync-article-count limit. Only works if Feed Commas is online. |
|
|
Toggles between offline and online modes. |
|
|
|
Opens selected article in a default web browser. Refer to the documentation of your Operating System on how to configure one.
Usually setting |
|
|
Quits Feed Commas. |
Key values can contain modifiers, but they heavily depend on what keycodes terminal sends. For example, terminals usually won’t explicitly send shift, but uppercase letters instead (so instead of mapping shift+e, map E).
Any combination of ctrl and alt modifiers is available as c-
and
a-
prefixes. Other keys are also available:
Key on keyboard | config.ini notation |
---|---|
ctrl |
|
alt |
|
shift |
|
↑ |
|
↓ |
|
← |
|
→ |
|
Enter |
|
Return |
|
Page Up |
|
Page Down |
|
F5 |
|
Examples |
|
ctrl+a |
|
alt+a |
|
ctrl+alt+← |
|
alt+Enter |
|
Use lower case
Non-character keys should be written lower-case! Instead of typing |
Settings
[settings]
section contains options affecting various behaviours of
Feed Commas.
Option | Default value | Description |
---|---|---|
|
|
Time (in seconds) after which currently selected article will be marked as read. If set to 0, articles will be marked as read immediately. If set to -1, articles won’t be automatically marked as read. It’s advised to be kept as positive integer, which will prevent marking articles as unread when scrolling through an article list. |
|
If set to true, all articles will be shown on the article list. If set to false, only unread articles will be shown. Using show-all or show-unread command automatically changes this setting so after application restart, the last state is used. |
|
|
|
Number of colors supported by terminal. Most terminals nowdays support at least 256 colors, so if things work for you, don’t change this setting. Valid values: 1, 16, 88, 256 |
|
|
Display bright colors as bold (some terminals work that way). Change it to true if you don’t see a difference when using bright colors. |
|
|
Method of filtering HTML in received entries so they’re readable. Can be either of the following:
|
|
When set to true, Feed Commas will only display articles which were previously saved for offline read and won’t request updates from remote Comma Feed service. When using Feed Commas in online mode, all articles are automatically saved and updated to match Comma Feed state. |
|
|
|
Some terminals and terminal multiplexers allow setting title of terminal window. If this option is set, Feed Commas will try to change a title to its value. |
|
|
Number of worker processes used for various tasks, like communicating with CommaFeed. If this option is unset, workers will be spawned in a number equal to available CPU cores. |
|
Parameters displayed on status line. The value of The following parameters are available:
|
|
|
Maximum number of articles to be downloaded from Comma Feed for offline access. It usually doesn’t make any sense to set this limit to more than 1000 because Comma Feed only stores the last 1000 RSS entries. |
html-filter commands usage
Both lynx and elinks work very well as The best results are achieved when they are configured with a dump wide enough, so that Feed Commas can take care of line wrapping: html-filter = elinks -dump -dump-width 500 html-filter = lynx -dump -width 500 -stdin |
Colors
Different parts of Feed Commas can be colorized to your liking by setting
different options in [colors]
section. Default values are sensible, but the
end-result depends on terminal’s color capabilities. Color can be empty, in
which case
Option | Default value | Affected elements |
---|---|---|
|
|
Color of article’s title. |
|
|
Color of currently selected article’s title. |
|
|
Color of currently selected article’s border. |
|
|
Various meta data information: article’s publication date, article’s header, various indicators on articles list, number of unread articles in menu etc. |
|
|
Foreground color of currently selected menu item. |
|
|
Background color of currently selected menu item. |
|
|
Color of currently active feed or category. |
|
|
Foreground color of status line. |
|
|
Background color of status line. |
|
|
Color of line separating menu and article list. |
|
|
Foreground color of errors displayed in commandline. |
|
|
Background color of errors displayed in commandline. |
Monochrome, 16-, 88- and 256-color terminals are supported. As a color name you can use any of standard color values: black, dark red, dark green, brown, dark blue, dark magenta, dark cyan, light gray, dark gray, light red, light green, yellow, light blue, light magenta, light cyan, white. For terminals which support that, you can also use other notations:
-
#fcc
: hex like HTML color; -
g40
: decimal value: 40% of gray -
g#cc
: hex value: 80% of gray -
h255
: color number 255
For different terminals colors are configured in different ways, but most often
they’re defined in ~/.Xresources
file. Consult your terminal’s documentation
for details.
Apart from color name, you can specify some text attributes, which should be placed after comma. These attributes include bold, underline, blink and standout. Color value can be omitted, in which case a default foreground or background color for your terminal will be used.
Setting | Description |
---|---|
|
Set color to "dark gray" standard color. |
|
Set font to bold red. |
|
Set font to bold. Default color will be used (depending on which option is set) |
Appendix A: Program options
The following parameters can be passed to Feed Commas when it’s started:
General options
- -c, --config=CONFIG_FILE
-
Use a CONFIG_FILE as Feed Commas' configuration file. This file is used instead of the one which would be normally found by a default configuration search. If CONFIG_FILE doesn’t exists, it is created.
Feed Commas reports if CONFIG_FILE is incorrect somehow or if it couldn’t be created and quits in that case.
Program information
- --help
-
Prints a short summary of available program options and quits.
- --version
-
Prints a version of Feed Commas and quits.
Appendix B: License
Copyright © 2017 Michał Góral.
Feed Commas is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Feed Commas is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Feed Commas. If not, see http://www.gnu.org/licenses/.