RSSaurus User Guide

RSSaurus is a personal RSS reader with a clean, inbox-style workflow — plus an API and CLI for automation.

  • Start here: add feeds, read items, save things for later
  • Power users: keyboard shortcuts + API tokens + agent-friendly endpoints

Table of contents

Getting started

  1. Sign up for an account.
  2. Add one or more feeds.
  3. Read items from All Items.
  4. Save items you want to come back to in Saved Items.

Feeds

Add a feed

Go to Feeds and add a URL.

  • RSSaurus will try to detect the feed from a normal website URL.
  • You can also paste a direct RSS/Atom feed URL.

Refresh feeds

RSSaurus refreshes feeds automatically in a few situations:

  • In the background (every ~5 minutes) for feeds that are stale
  • On login
  • Manually via refresh actions in the UI

Feeds have a built-in staleness guard (about 15 minutes), so background refresh won't hammer the same feed too frequently.

(If you ever suspect a feed is stuck, try a manual refresh first.)

Reading items (inbox-style)

RSSaurus is meant to feel like an inbox:

  • New items show up as unread
  • You can mark items read/unread
  • You can mark all items read for a feed when you want to clear the deck

Preview vs full content

RSSaurus can show items as a preview, and you can click into the full item view.

Saved Items (read/watch later)

Saved Items are your “come back later” queue.

Save something manually

You can save an item from within RSSaurus.

Save from anywhere (Bookmarklet)

RSSaurus includes a bookmarklet that lets you save the current page to RSSaurus.

  1. Go to Saved Items
  2. Click Install Bookmarklet
  3. Add the bookmarklet to your bookmarks bar
  4. When you’re on a page you want to save, click the bookmarklet

Note: you must be logged in for the bookmarklet to work.

API tokens

If you want to use the API (or the CLI), you’ll need an API token.

  • Go to Settings → API Tokens
  • Create a token
  • Treat tokens like passwords (don’t paste them into screenshots or share them)

Tokens can have scopes (permissions). If your token is missing a required scope, the API will return an error that names the missing scope.

API + CLI

RSSaurus includes:

  • A token-based API
  • OpenAPI spec at /openapi.json
  • API docs at /docs/api and /docs/api.md

CLI (rssaurus-cli)

If you want to drive RSSaurus from scripts or an agent runner, the official CLI can be simpler than raw curl:

Webhooks (push notifications)

If you prefer event-driven automation (instead of polling), RSSaurus can send a signed webhook when new items arrive.

  • Go to Settings → Webhooks
  • Add an HTTPS webhook URL
  • RSSaurus will POST a JSON payload with new items

Webhook payloads are signed with an HMAC secret. See /docs/api for the exact payload format and signature verification.

Keyboard shortcuts

RSSaurus has a few built-in shortcuts for faster reading.

On the item list (All Items)

  • j: move down (and open preview)
  • k: move up (and open preview)
  • Arrow Down / Arrow Up: move selection down/up
  • Enter: open the selected item
  • o: open preview for the selected item
  • r: toggle read/unread for the selected item

On an item page

  • Left Arrow: previous item
  • Right Arrow: next item

Tip: shortcuts do not trigger while you’re typing in an input or textarea.

Rich media (podcasts, YouTube, etc.)

RSSaurus supports rich media so your reading queue can include more than text.

Audio / podcasts

If an item includes an audio enclosure (common in podcast feeds), RSSaurus will show an inline audio player so you can listen without leaving the app.

Embedded media

RSSaurus can embed certain media links directly inside an item view (when the feed content includes a supported link), including:

  • YouTube
  • Vimeo
  • Apple Podcasts
  • Twitch
  • TikTok

If RSSaurus can’t safely embed a particular URL, it will still show the link normally.

Billing / trial

  • RSSaurus offers a 30-day free trial.
  • After the trial, the current price is $20/year.

Account retention

If your trial ends or your subscription expires and your account remains inactive, RSSaurus may delete your account and associated data after 90 days.

Support

If something’s not working, go to /support.

The Support page will generate an email to support@rssaurus.com and includes helpful diagnostics (browser + page URL, and if you’re signed in, your user id + account status).