Command-line interface

reader comes with a CLI that exposes management functionality.

Note

The CLI 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 web

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 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 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 command-line interface.

Option defaults can be set via environment variables; unless documented otherwise, the format is READER[_SUBCOMMAND]_OPTION.

https://reader.readthedocs.io/

Usage

reader [OPTIONS] COMMAND [ARGS]...

Options

--url, --db <url>

Path to the reader database.

Default:

'/home/docs/.config/reader/db.sqlite'

--feed-root <feed_root>

Directory local feeds are relative to. ‘’ (empty string) means full filesystem access. If not provided, don’t open local feeds.

Default:

Sentinel.UNSET

--read-only, --no-read-only

Do not modify storage.

--plugin <plugins>

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

--cli-plugin <cli_plugins>

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

--reserved-name-scheme <reserved_name_scheme>
Default:

'reader_prefix=.reader., plugin_prefix=.plugin., separator=.'

--config <config>

Path to the reader config.

Default:

'/home/docs/.config/reader/config.toml'

--version

Show the version and exit.

add

Add a new feed.

Usage

reader add [OPTIONS] URL

Options

--update, --no-update

Update the feed after adding it.

-v, --verbose

Arguments

URL

Required argument

delete

Delete an existing feed.

Usage

reader delete [OPTIONS] URL

Options

-v, --verbose

Arguments

URL

Required argument

list

List feeds or entries.

Usage

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>

Usage

reader list entries [OPTIONS]

Options

--json

Output as JSON.

feeds

List all the feeds.

Usage

reader list feeds [OPTIONS]

Options

--json

Output as JSON.

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

Usage

reader update [OPTIONS] [URL]

Options

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

Only update new (never updated before) feeds.

--scheduled, --no-scheduled

Only update feeds scheduled to be updated.

Default:

True

--workers <workers>

Number of threads to use when getting the feeds.

Default:

1

-v, --verbose

Arguments

URL

Optional argument