NEWSBEUTER(1)

NAME
newsbeuter - an RSS feed reader for text terminals

SYNOPSIS
newsbeuter [-r] [-e] [-i opmlfile] [-u urlfile] [-c cachefile] [-C configfile] [-v] [-o] [-h]

DESCRIPTION
newsbeuter is an RSS feed reader for text terminals. RSS is a number of widely-used XML formats to transmit, publish and syndicate articles, for example news or blog articles. Newsbeuter is designed to be used on text terminals on Unix or Unix-like systems such as Linux, BSD or Mac OS X.

OPTIONS

-h  Display help

-r  Refresh feeds on start

-e  Export feeds as OPML to stdout

-v  Clean up cache thoroughly (i.e. reduce it in size if possible)

-V  Get version information about newsbeuter and the libraries it uses

-i opmlfile
    Import an OPML file

-u urlfile
    Use an alternative URL file

-c cachefile
    Use an alternative cache file

-C configfile
    Use an alternative configuration file

-o  Active offline reading mode. When bloglines synchronization mode is configured, then the list of feeds will not be loaded from bloglines.com, but instead from the local cache. This makes it possible to read locally cached articles even without internet connection to connect to the bloglines server.

FIRST STEPS
After you've installed newsbeuter, you can run it for the first time by typing "newsbeuter" on your command prompt. This will bring you the following message:
Error: no URLs configured. Please fill the file /Users/ak/.newsbeuter/urls with RSS feed URLs or import an OPML file.
newsbeuter 0.7
usage: ./newsbeuter [-i <file>|-e] [-u <urlfile>] [-c <cachefile>] [-h]
-e              export OPML feed to stdout
-r              refresh feeds on start
-i <file>       import OPML file
-u <urlfile>    read RSS feed URLs from <urlfile>
-c <cachefile>  use <cachefile> as cache file
-C <configfile> read configuration from <configfile>
-v              clean up cache thoroughly
-o              activate offline mode (only applies to bloglines synchronization mode)
-V              get version information
-h              this help
This means that newsbeuter can't start without any configured feeds. To add feeds to newsbeuter, you can either add URLs to the configuration file $HOME/.newsbeuter/urls or you can import an OPML file by running "newsbeuter -i blogroll.opml". To manually add URLs, open the file with your favorite text editor and add the URLs, one per line:
http://rss.cnn.com/rss/cnn_topstories.rss
http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml
If you need to add URLs that have restricted access via username/password, simply provide the username/password in the following way:
http://username:password@hostname.domain.tld/feed.rss
In order to protect username and password, make sure that $HOME/.newsbeuter/urls has the appropriate permissions. Now you can run newsbeuter again, and it will present you with a controllable list of the URLs that you configured previously. You can now start downloading the feeds, either by pressing "R" to download all feeds, or by pressing "r" to download the currently selected feed. You can then select a feed you want to read, and by pressing "Enter", you can go to the article list for this feed. This works even while the downloading is still in progress. You can now see the list of available articles by their title. A "N" on the left indicates that an article wasn't read yet. Pressing Enter brings you to the content of the article. You can scroll through this text, and also run a browser (default: lynx) to view the complete article if the content is empty or just an abstract or a short description. Pressing "q" brings you back to the article list, and pressing "q" again brings you back to the feed list. Pressing "q" a third time then closes newsbeuter. Newsbeuter caches the article that it downloads. This means that when you start newsbeuter again and reload a feed, the old articles can still be read even if they aren't in the current RSS feeds anymore. Optionally you can configure how many articles shall be preserved by feed so that the article backlog doesn't grow endlessly (see below). Several aspects of newsbeuter's behaviour can be configured via a configuration file, by default $HOME/.newsbeuter/config. This configuration files contains lines in the form "<config-command> <arg1> ...". The configuration file can also contain comments, which start with the # character and go as far as the end of line. If you need to enter a configuration argument that contains spaces, use quotes (") around the whole argument. Searching for articles is possible in newsbeuter, too. Just press the "/" key, enter your search phrase, and the title and content of all articles are searched for it. When you do a search from the list of feeds, all articles of all feeds will be searched. When you do a search from the article list of a feed, only the articles of the currently viewed feed are searched.

CONFIGURATION COMMANDS

auto-reload (parameters: [yes/no]; default value: no)
    If enabled, all feeds will be automatically reloaded at start up and then continuously after a certain time has passed (see reload-time). (example: auto-reload yes)

bind-key (parameters: <key> <operation>; default value: n/a)
    Bind key <key> to <operation>. This means that whenever <key> is pressed, then <operation> is executed (if applicable in the current context). A list of available operations can be found below. (example: bind-key ^R reload-all)

bookmark-cmd (parameters: <command>; default value: "")
    If set, the configured command will be used as bookmark plugin. Please refer to the documentation for further information on bookmark plugins. (example: bookmark-cmd "~/bin/my-bookmark-plugin.sh")

bloglines-auth (parameters: <login>:<password>; default value: "")
    Set the Bloglines username and password. This is necessary for the Bloglines synchronization mode. (example: bloglines-auth "username@emailaddress.com:mypassword")

bloglines-mark-read (parameters: [yes/no]; default value: no)
    If set to yes, it will mark all articles that are downloaded from Bloglines as read. (example: bloglines-mark-read yes)

bookmark-cmd (parameters: <bookmark-command>; default value: "")
    If set, then <bookmark-command> will be used as bookmarking plugin. See the documentation on bookmarking for further information. (example: bookmark-cmd "~/bin/delicious-bookmark.sh")

browser (parameters: <browser-command>; default value: lynx)
    Set the browser command to use when opening an article in the browser. (example: browser w3m)

cache-file (parameters: <path>; default value: "~/.newsbeuter/cache.db")
    This configuration option sets the cache file. This is especially useful if the filesystem of your home directory doesn't support proper locking (e.g. NFS). (example: cache-file "/tmp/testcache.db")

cleanup-on-quit (parameters: [yes/no]; default value: yes)
    If yes, then the cache gets locked and superfluous feeds and items are removed, such as feeds that can't be found in the urls configuration file anymore. (example: cleanup-on-quit no)

color (parameters: <element> <fgcolor> <bgcolor> [<attr> ...]; default value: n/a)
    Set the foreground color, background color and optional attributes for a certain element (example: color background white black)

confirm-exit (parameters: [yes/no]; default value: no)
    If set to yes, then newsbeuter will ask for confirmation whether the user really wants to quit newsbeuter. (example: confirm-exit yes)

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 the allowed formats, consult the manpage of strftime(3). (example: datetime-format "%D, %R")

define-filter (parameters: <name> <filter>; default value: n/a)
    With this command, you can predefine filters, which can you later select from a list, and which are then applied after selection. This is especially useful for filters that you need often and you don't want to enter them every time you need them. (example: define-filter "all feeds with fun tag" "tags # \\"fun\\"")

error-log (parameters: <path>; default value: "")
    If set, then user errors (e.g. errors regarding defunct RSS feeds) will be logged to this file. (example: error-log "~/.newsbeuter/error.log")

html-renderer (parameters: <path>; default value: internal)
    If set to "internal", then the internal HTML renderer will be used. Otherwise, the specified command will be executed, the HTML to be rendered will be written to the command's stdin, and the program's output will be displayed. This makes it possible to use other, external programs, such as w3m, links or lynx, to render HTML. (example: html-renderer "w3m -dump -T text/html")

ignore-article (parameters: <feed> <filterexpr>; default value: n/a)
    If a downloaded article from <feed> matches <filterexpr>, then it is ignored and not presented to the user. This command is further explained in the "kill file" section below. (example: ignore-article "*" "title =~ \\"Windows\\"")

include (parameters: <path>; default value: n/a)
    With this command, you can include other files to be interpreted as configuration files. This is especially useful to separate your configuration into several files, e.g. key configuration, color configuration, ... (example: include "~/.newsbeuter/colors")

max-items (parameters: <number>; default value: 0)
    Set the number of articles to maximally keep per feed. If the number is set to 0, then all articles are kept. (example: max-items 100)

notify-program (parameters: <path>; default value: "")
    If set, then the configured program will be executed if new articles arrived (through a reload). The first parameter of the called program contains the notification message. (example: notify-program "~/bin/my-notifier")

notify-screen (parameters: [yes/no]; default value: no)
    If yes, then a "privacy message" will be sent to the terminal, containing a notification message about new articles. This is especially useful if you use terminal emulations such as GNU screen which implement privacy messages. (example: notify-screen yes)

notify-xterm (parameters: [yes/no]; default value: no)
    If yes, then the xterm window title will be set to a notification message about new articles. (example: notify-xterm yes)

podcast-auto-enqueue (parameters: [yes/no]; default value: no)
    If yes, then all podcast URLs that are found in articles are added to the podcast download queue. See below for more information on podcast support in newsbeuter. (example: podcast-auto-enqueue yes)

opml-url (parameters: <url>; default value: "")
    If the OPML online subscription mode is enabled, then the list of feeds will be taken from the OPML file found on this location. (example: opml-url "http://host.domain.tld/blogroll.opml")

proxy (parameters: <server:port>; default value: n/a)
    Set the proxy to use for downloading RSS feeds. (example: proxy localhost:3128)

proxy-auth (parameters: <auth>; default value: n/a)
    Set the proxy authentication string. (example: proxy-auth user:password)

refresh-on-startup (parameters: [yes/no]; default value: no)
    If yes, then all feeds will be reloaded when newsbeuter starts up. This is equivalent to the -r commandline option. (example: refresh-on-startup yes)

reload-time (parameters: <number>; default value: 30)
    The number of minutes between automatic reloads. (example: reload-time 60)

save-path (parameters: <path>; default value: ~/)
    The default path where articles shall be saved to. If an invalid path is specified, the current directory is used. (example: save-path "~/Saved Articles")

show-read-feeds (parameters: [yes/no]; default value: yes)
    If yes, then all feeds, including those without unread articles, are listed. If no, then only feeds with one or more unread articles are list. (example: show-read-feeds no)

suppress-first-reload (parameters: [yes/no]; default value: no)
    If yes, then the first automatic reload will be suppressed if auto-reload is set to yes. (example: suppress-first-reload yes)

unbind-key (parameters: <key>; default value: n/a)
    Unbind key <key>. This means that no operation is called when <key> is pressed. (example: unbind-key R)

urls-source (parameters: <source>; default value: "local")
    This configuration command sets the source where URLs shall be retrieved from. By default, this is ~/.newsbeuter/urls. Alternatively, you can set it to "bloglines", which enables newsbeuter's Bloglines synchronization mode, or to "opml", which enables newsbeuter's OPML online subscription mode. (example: urls-source "bloglines")

use-proxy (parameters: [yes/no]; default value: no)
    If yes, then the configured proxy will be used for downloading the RSS feeds. (example: use-proxy yes)

user-agent (parameters: <user agent string>; default value: "")
    If set to a non-zero-length string, this value will be used as HTTP User-Agent header for all HTTP requests. (example: user-agent "Lynx/2.8.5rel.1 libwww-FM/2.14")

TAGGING
Newsbeuter comes with the possibility to categorize or "tag", as well call it, RSS feeds. Every RSS feed can be assigned 0 or more tags. Within newsbeuter, you can then select to only show RSS feeds that match a certain tag. That makes it easy to categorize your feeds in a flexible and powerful way. Usually, the /.newsbeuter/urls file contains one RSS feed URL per line. To assign a tag to an RSS feed, simply attach it as a single word, separated by blanks such as space or tab. If the tag needs to contain spaces, you must use quotes (") around the tag (see example below). An example /.newsbeuter/urls file may look like this:
http://blog.fefe.de/rss.xml?html interesting conspiracy news "cool stuff"
http://rss.orf.at/news.xml news orf
http://www.heise.de/newsticker/heise.rdf news interesting
When you now start newsbeuter with this configuration, you can press "t" to select a tag. When you select the tag "news", you will see all three RSS feeds. Pressing "t" again and e.g. selecting the "conspiracy" tag, you will only see the http://blog.fefe.de/rss.xml?html RSS feed. Pressing "^T" clears the current tag, and again shows all RSS feeds, regardless of their assigned tags.

SCRIPTS AND FILTERS
From version 0.4 on, newsbeuter contains support for Snownews extensions. The RSS feed readers Snownews and Liferea share a common way of extending the readers with custom scripts. Two mechanisms, namely "execurl" and "filter" type scripts, are available and supported by newsbeuter. 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 ~/.newsbeuter/urls file configuration lines like the following ones:
exec:~/bin/execurl-script
filter:~/bin/filter-script:http://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:
"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:
"filter:~/bin/filter-script param1 param2:http://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:http://some.test/url tag3 tag4 tag5
A collection of such extension scripts can be found on this website: http://kiza.kcore.de/software/snownews/snowscripts/extensions If you want to write your own extensions, refer to this website for further instructions: http://kiza.kcore.de/software/snownews/snowscripts/writing

COMMAND LINE
Like other text-oriented software, newsbeuter contains an internal commandline to modify configuration variables ad hoc and to run own commands. It provides a flexible access to the functionality of newsbeuter 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 return key executes the command (possibly giving feedback to the user) and closes the commandline. You can cancel entering commands by pressing the ESC key. Currently, the following commands are available:

quit
    Quit newsbeuter

save <filename>
    Save current article to <filename>

set <variable>[=<value>]
    Set (or get) configuration variable value

tag <tagname>
    Select a certain tag

<number>
    Jump to the <number>th entry in the current dialog

FILES
$HOME/.newsbeuter/config $HOME/.newsbeuter/urls

SEE ALSO
podbeuter(1). The documentation that comes with newsbeuter is a good source about the general use and configuration of newsbeuter.

AUTHORS
Andreas Krennmair <ak@synflood.at>, for contributors see AUTHORS file.