Getting started
Requirements
Python 3.12 or newer and uv. If you use mise, the pinned versions come from mise.toml.
uv tool install 'rssd-fs[tui]' # from PyPI, with the terminal reader
brew install alliecatowo/tap/rssd # or Homebrew, macOS and LinuxThat 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.
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 itAlready 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:
tail -F ~/.local/share/rssd/var/events.jsonl | jq -cAdding a feed
A subscription is one XML file. Drop it in and the daemon picks it up without a restart.
cat > ~/.local/share/rssd/feeds.d/lwn.xml <<'XML'
<subscription>
<url>https://lwn.net/headlines/rss</url>
<name>lwn</name>
<interval>30m</interval>
</subscription>
XMLOnly <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:
uv run rssd prune --retired --yesRunning offline
Every test fixture is committed, so the whole system runs with no network:
uv run rssd init demo/ --fixture-mode
uv run rssd serve-fixtures --dir demo/fixtures # separate terminal
uv run rssd daemon --root demo --poll-nowUseful 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.jsonlstore/ 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.