Skip to content

Getting started ​

Requirements ​

Python 3.12 or newer and uv. If you use mise, the pinned versions come from mise.toml.

bash
uv tool install 'rssd-fs[tui]'      # from PyPI, with the terminal reader
brew install alliecatowo/tap/rssd   # or Homebrew, macOS and Linux

That installs two commands: rssd (the daemon) and rss (the reader). Check with rssd --version; this site documents 0.3.0.

To hack on it instead: git clone https://github.com/alliecatowo/rssd, then uv sync --extra tui and prefix commands below with uv run.

Your first instance ​

An instance is one directory. Everything rssd knows lives under it, so you can move it, tar it, or delete it with no other state to clean up. By default it is $RSSD_ROOT or ~/.local/share/rssd, created for you on first use; use --root DIR for another.

bash
rssd add https://blog.rust-lang.org/feed.xml --name rust-blog   # subscribe
rssd once                                      # poll everything now
rss list                                       # what's subscribed, and is it healthy
rss tui                                        # read it

Already use another reader? rssd import subscriptions.opml subscribes to every feed in an OPML file, and rssd export writes your list back out. See OPML import and export.

Use rssd daemon instead of rssd once to keep polling in the background (--poll-now skips the startup stagger).

rssd init additionally scaffolds six reference feeds chosen to exercise every code path — a high-churn one, a rich Atom one, a thin RSS one, an image-only one, and one that sends no cache validators at all.

To watch the raw event stream:

bash
tail -F ~/.local/share/rssd/var/events.jsonl | jq -c

Adding a feed ​

A subscription is one XML file. Drop it in and the daemon picks it up without a restart.

bash
cat > ~/.local/share/rssd/feeds.d/lwn.xml <<'XML'
<subscription>
  <url>https://lwn.net/headlines/rss</url>
  <name>lwn</name>
  <interval>30m</interval>
</subscription>
XML

Only <url> is required. <name> defaults to the filename stem, <interval> to an adaptive default, and <fulltext> to false.

Deleting the file stops polling but never deletes what was already harvested — the folder is marked retired and left alone. Cleanup is an explicit rss-free command:

bash
uv run rssd prune --retired --yes

Running offline ​

Every test fixture is committed, so the whole system runs with no network:

bash
uv run rssd init demo/ --fixture-mode
uv run rssd serve-fixtures --dir demo/fixtures    # separate terminal
uv run rssd daemon --root demo --poll-now

Useful on a plane, and useful when you'd rather a live demo not depend on somebody else's uptime.

Where things go ​

demo/
├── feeds.d/     you write these
├── store/       the daemon writes these — only ever feed folders
└── var/         daemon-private state, plus events.jsonl

store/ contains nothing but feed directories, so ls store/ is always meaningful. Bookkeeping lives in a sibling directory rather than a dotfile inside it, because grep -r, find and rsync all traverse dotfiles anyway.

Released under the MIT License.