Command-line interface

This part of the documentation covers the reader command-line interface.

Warning

The CLI is not stable yet and might change without any notice.

Note

The command-line interface is optional, use the cli extra to install its dependencies.

Most commands need a database to work. The following are equivalent:

python -m reader --db /path/to/db some-command
READER_DB=/path/to/db python -m reader some-command

If no database path is given, ~/.config/reader/db.sqlite is used (at least on Linux).

Add a feed:

python -m reader add http://www.example.com/atom.xml

Update all feeds:

python -m reader update

Serve the web application locally (at http://localhost:8080/):

python -m reader serve

Updating feeds

For reader to actually be useful as a feed reader, feeds need to get updated and, if full-text search is enabled, the search index needs to be updated.

You can run the update command regularly to update feeds (e.g. every hour). Note that reader uses the ETag and Last-Modified headers, so, if supported by the the server, feeds will only be downloaded if they changed.

To avoid waiting too much for a new feed to be updated, you can run update --new-only more often (e.g. every minute); this will update only newly-added feeds. This is also a good time to update the search index.

You can achieve this using cron:

42 * * * *  reader update -v 2>&1 >>"/tmp/$LOGNAME.reader.update.hourly.log"
* * * * *   reader update -v --new-only 2>&1 >>"/tmp/$LOGNAME.reader.update.new.log"; reader search update 2>&1 >>"/tmp/$LOGNAME.reader.search.update.log"

If you are running reader on a personal computer, it might also be convenient to run update once immediately after boot:

@reboot     sleep 60; reader update -v 2>&1 >>"/tmp/$LOGNAME.reader.update.boot.log"

Reference

reader

reader [OPTIONS] COMMAND [ARGS]...

Options

--db <db>

Path to the reader database. [default: /home/docs/.config/reader/db.sqlite]

--plugin <plugin>

Import path to a reader plug-in. Can be passed multiple times.

--config <config>

Path to the reader config.

Default:/home/docs/.config/reader/config.yaml
--version

Show the version and exit.

Environment variables

READER_DB
Provide a default for --db
READER_PLUGIN
Provide a default for --plugin
READER_CONFIG
Provide a default for --config

add

Add a new feed.

reader add [OPTIONS] URL

Options

--update, --no-update

Update the feed after adding it.

-v, --verbose

Arguments

URL

Required argument

config

Do various things related to config.

reader config [OPTIONS] COMMAND [ARGS]...
dump
reader config dump [OPTIONS]

Options

--merge, --no-merge

list

List feeds or entries.

reader list [OPTIONS] COMMAND [ARGS]...
entries

List all the entries.

Outputs one line per entry in the following format:

<feed URL> <entry link or id>
reader list entries [OPTIONS]
feeds

List all the feeds.

reader list feeds [OPTIONS]

remove

Remove an existing feed.

reader remove [OPTIONS] URL

Options

-v, --verbose

Arguments

URL

Required argument

serve

Start a local HTTP reader server.

reader serve [OPTIONS]

Options

-h, --host <host>

The interface to bind to.

-p, --port <port>

The port to bind to.

--plugin <plugin>

Import path to a web app plug-in. Can be passed multiple times.

-v, --verbose

Environment variables

READER_APP_PLUGIN
Provide a default for --plugin

update

Update one or all feeds.

If URL is not given, update all the feeds.

Verbosity works like this:

: progress bar + final status
-v: + lines
-vv: + warnings
-vvv: + info
-vvvv: + debug
reader update [OPTIONS] [URL]

Options

--new-only, --no-new-only

Only update new (never updated before) feeds.

--workers <workers>

Number of threads to use when getting the feeds.

Default:1
-v, --verbose

Arguments

URL

Optional argument