# rss-tui
rss-tui [*russ-tooey*] is based on russ, which is a TUI RSS/Atom reader with vim-like controls, written in [Rust](https://rust-lang.org/).
This is a new repo from a personal fork of [ckampfe/russ](https://github.com/ckampfe/russ), with a few improvements.
[](https://crates.io/crates/rss-tui)
[](https://github.com/shalloran/rss-tui/actions/workflows/ci.yml)
---
*rss-tui in all its text-based glory*
## install
### From crates.io (recommended):
```console
cargo install rss-tui
```
Note that on linux, you may need additional system dependencies as well, for example:
```console
sudo apt update && sudo apt install libxcb-shape0-dev libxcb-xfixes0-dev
```
The binary will be installed as `rss-tui`. You can run it with:
```console
rss-tui read
```
**Note:** At this time, only macOS and Linux are tested. If you are using this on Windows, reach out!
### From this repository:
```console
cargo install rss-tui --git https://github.com/shalloran/rss-tui
```
**Note:** This is a fork with some additional features. If you want the original, use: `cargo install russ --git https://github.com/ckampfe/russ`.
**Note:** If you want to force overwrite an existing installation, use:
`cargo install --force rss-tui` (from crates.io) or `cargo install --force --git https://github.com/shalloran/rss-tui rss-tui` (from git)
**Note** that on its first run with no arguments, `rss-tui read` creates a SQLite database file called `feeds.db` to store RSS/Atom feeds in a location of its choosing. If you wish to override this, you can pass a path with the `-d` option, like `rss-tui -d /your/database/location/my_feeds.db`. If you use a custom database location, you will need to pass the `-d` option every time you invoke `rss-tui`. See the help with `rss-tui -h` for more information about where `rss-tui` will store the `feeds.db` database by default on your platform.
## use
rss-tui is modal, like vim. If you read the following controls section and tinker a bit, you'll have no trouble using rss-tui.
There are two modes: normal mode and insert mode.
### controls - normal mode
Some normal mode controls vary based on whether you are currently selecting a feed or an entry:
- `q`/`Esc` - quit rss-tui
- `hjkl`/arrows - move up/down/left/right between feeds and entries, scroll up/down on an entry
- `Enter` - read selected entry
- `r` - refresh the selected feed (when feeds selected) or mark entry as read/unread (when entries selected)
- `x` - refresh all feeds
- `i`/`e` - change to insert mode (when feeds selected)
- `e` - email the current article (when viewing an entry; opens your default email client with the article title as subject and URL as body)
- `a` - toggle between read/unread entries
- `c` - copy the selected link to the clipboard (feed or entry)
- `o` - open the selected link in your browser (feed or entry)
- `d` - delete the selected feed (with confirmation; press `d` again to confirm, `n` to cancel)
- `E` - export all feeds to an OPML file (saves to a timestamped file in your database directory)
- `ctrl-u`/`ctrl-d` - scroll up/down a page at a time
### controls - insert mode
- `Esc` - go back to normal mode
- `Enter` - subscribe to the feed you just typed in the input box
- `Del` - delete the selected feed
## help/options/config
```console
rss-tui -h
A TUI RSS reader with vim-like controls and a local-first, offline-first focus
Usage: rss-tui <COMMAND>
Commands:
read Read your feeds
import Import feeds from an OPML document
export Export feeds to an OPML document
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
## read mode
```console
rss-tui read -h
Read your feeds
Usage: rss-tui read [OPTIONS]
Options:
-d, --database-path <DATABASE_PATH>
Override where `rss-tui` stores and reads feeds. By default, the feeds database on Linux this will be at `XDG_DATA_HOME/rss-tui/feeds.db` or `$HOME/.local/share/rss-tui/feeds.db`. On MacOS it will be at `$HOME/Library/Application Support/rss-tui/feeds.db`. On Windows it will be at `{FOLDERID_LocalAppData}/rss-tui/data/feeds.db`
-t, --tick-rate <TICK_RATE>
time in ms between two ticks [default: 250]
-f, --flash-display-duration-seconds <FLASH_DISPLAY_DURATION_SECONDS>
number of seconds to show the flash message before clearing it [default: 4]
-n, --network-timeout <NETWORK_TIMEOUT>
RSS/Atom network request timeout in seconds [default: 5]
-h, --help
Print help
```
## import OPML mode
```console
rss-tui import -h
Import feeds from an OPML document
Usage: rss-tui import [OPTIONS] --opml-path <OPML_PATH>
Options:
-d, --database-path <DATABASE_PATH>
Override where `rss-tui` stores and reads feeds. By default, the feeds database on Linux this will be at `XDG_DATA_HOME/rss-tui/feeds.db` or `$HOME/.local/share/rss-tui/feeds.db`. On MacOS it will be at `$HOME/Library/Application Support/rss-tui/feeds.db`. On Windows it will be at `{FOLDERID_LocalAppData}/rss-tui/data/feeds.db`
-o, --opml-path <OPML_PATH>
-n, --network-timeout <NETWORK_TIMEOUT>
RSS/Atom network request timeout in seconds [default: 5]
-h, --help
Print help
```
## export OPML mode
```console
rss-tui export -h
Export feeds to an OPML document
Usage: rss-tui export [OPTIONS] --opml-path <OPML_PATH>
Options:
-d, --database-path <DATABASE_PATH>
Override where `rss-tui` stores and reads feeds. By default, the feeds database on Linux this will be at `XDG_DATA_HOME/rss-tui/feeds.db` or `$HOME/.local/share/rss-tui/feeds.db`. On MacOS it will be at `$HOME/Library/Application Support/rss-tui/feeds.db`. On Windows it will be at `{FOLDERID_LocalAppData}/rss-tui/data/feeds.db`
-o, --opml-path <OPML_PATH>
Path where the OPML file will be written
-h, --help
Print help
```
You can also export from within the TUI by pressing `E` (capital E) in normal mode. This will create a timestamped OPML file in the same directory as your database.
## design
rss-tui is a [tui](https://crates.io/crates/tui) app that uses [crossterm](https://crates.io/crates/crossterm). rss-tui stores all application data in a SQLite database.
## features/todo
This is not a roadmap, just a list of potential features.
### my feature list
- [x] visual indicator for which feeds have new/unacknowledged entries (partially complete)
- [x] bug: text wrapping has been sorted
- [ ] create a secure github -> crates.io publishing workflow
- [ ] sync / online mode?
- [ ] integration with ollama or LMStudio for local summarization
## Minimum Supported Rust Version (MSRV) policy
rss-tui targets the latest stable version of the Rust compiler. Older Rust version may work, but we are not supporting them.
## SQLite version
`rss-tui` compiles and bundles its own embedded SQLite via the [Rusqlite](https://github.com/rusqlite/rusqlite) project, which is version 3.45.1.
If you prefer to use the version of SQLite on your system, edit `Cargo.toml` to
remove the `"bundled"` feature from the `rusqlite` dependency and recompile `rss-tui`.
## contributing
The original project welcomes contributions. If you have an idea for something you would like to contribute to the original, open an issue on [ckampfe/russ](https://github.com/ckampfe/russ) and they can address it. For this fork, I'm happy to consider pull requests, and fix bugs, but keep in mind this is primarily for my own use. If you want a feature that's more broadly useful, please consider contributing to the upstream project as well.
## license
See the [license.](LICENSE)
SPDX-License-Identifier: AGPL-3.0-or-later
