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
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]
remove¶
Remove an existing feed.
reader remove [OPTIONS] URL
Options
- -v, --verbose¶
Arguments
- URL¶
Required argument
search¶
Do various things related to search.
reader search [OPTIONS] COMMAND [ARGS]...
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:
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