RSS Agent Viewer

CLI RSS/Atom feed viewer with automatic feed discovery via rss-agent-discovery.

Installation

npm install -g rss-agent-viewer

Or run without installation:

npx rss-viewer

Agent Skills

Install the AI agent skill with Skills CLI:

npx skills add brooksy4503/rss-agent-viewer --skill rss-agent-viewer

More info about the Skills CLI: https://skills.sh/

Quick Start

# Initialize configuration
rss-viewer init

# Add a feed
rss-viewer add https://vercel.com/atom

# List all feeds
rss-viewer feeds

# Read articles
rss-viewer read

Commands

• init - Initialize configuration and database
• add <url> - Add a feed to the database (supports --discover, --category, --timeout)
• discover <url> - Discover feeds from a URL
• feeds - List all subscribed feeds
• remove <url> - Remove a feed by URL
• read [url] - Read articles from a feed or all feeds (fetches fresh by default; supports --cached, --timeout, --overall-timeout)
• search <query> - Search across all feeds (local or web)
• discover-search <query> - Search web, discover feeds, add, and search articles
• import <file> - Import feeds from OPML file
• export - Export feeds to OPML or JSON
• cache <action> - Manage cache (stats, clear, refresh)
• cleanup - Remove broken and duplicate feeds

Read Command

The read command fetches fresh articles from all feeds by default with parallel processing:

# Fetch and read latest articles from all feeds
rss-viewer read

# Read from a specific feed
rss-viewer read https://techcrunch.com/feed/

# Use cached data only (skip network requests)
rss-viewer read --cached

# Limit results
rss-viewer read --limit 10

# Show latest item from different feeds (one per feed)
rss-viewer read --latest-per-feed --limit 10

Options:

• --cached - Use cached data only, skip fetching
• --limit <n> - Maximum number of articles (default: 20)
• --since <date> - Show articles newer than date
• --author <name> - Filter by author
• --tag <tag> - Filter by tag/category
• --reverse - Show oldest articles first
• --latest-per-feed - Show only the latest article from each feed (all-feeds mode)
• --timeout <ms> - Per-feed fetch timeout in milliseconds (default: from config, typically 10000)
• --overall-timeout <ms> - Overall fetch timeout when reading all feeds (default: from config, typically 120000)

Add Command

When adding a feed, you can override the fetch timeout used to resolve the feed title (e.g. after --discover):

# Add with discovery (uses config feedTimeout for the title fetch)
rss-viewer add https://example.com --discover

# Use a longer timeout for slow feeds
rss-viewer add https://slow-site.com/feed.xml --timeout 30000

Options:

• --discover - Auto-discover feeds from the URL
• --category <name> - Feed category (default: General)
• --timeout <ms> - Per-feed fetch timeout in milliseconds (when resolving title after discovery)

Cleanup Command

Remove invalid feeds from your database:

# Remove both broken and duplicate feeds
rss-viewer cleanup

# Only remove broken feeds (404s, timeouts, non-feed URLs)
rss-viewer cleanup --broken

# Only remove duplicate feeds from same domain
rss-viewer cleanup --duplicates

# Preview what would be removed
rss-viewer cleanup --dry-run

Options:

• --broken - Only remove feeds that fail to fetch
• --duplicates - Only remove duplicate feeds from same domain
• --dry-run - Show what would be removed without removing

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode
npm run dev

Configuration

Feed timeouts

Per-feed and overall fetch timeouts can be set in config or overridden by CLI:

• Per-feed timeout – applied to each feed fetch (add, read, discover-search). Default: 10000 ms. Env: RSS_FEED_TIMEOUT.
• Overall timeout – when reading all feeds (rss-viewer read), the whole operation is capped. Default: 120000 ms.

Config file (~/.config/rss-viewer/config.json):

{
  "feedTimeout": 10000,
  "overallTimeout": 120000
}

Web Search

The discover-search command supports web search via:

1. Agent Search (default) - Uses agent's built-in search capabilities
2. Exa API (BYOK) - Optional API integration for semantic search

Environment Variables:

EXA_API_KEY="your-api-key"                    # Exa API key (optional)
RSS_VIEWER_SEARCH_PROVIDER="agent|exa"        # Search provider (default: agent)
RSS_VIEWER_MAX_WEB_RESULTS=10                 # Max web search results
RSS_VIEWER_SEARCH_LIMIT=20                    # Max article results
RSS_VIEWER_BOOST_RECENT=false                # Boost recent articles in search
EXA_API_URL="https://api.exa.ai/search"      # Custom Exa endpoint (optional)

Config File (~/.config/rss-viewer/config.json):

{
  "webSearchProvider": "exa",
  "exaApiKey": "your-api-key",
  "exaApiUrl": "https://api.exa.ai/search",
  "maxWebResults": 10,
  "searchResultsLimit": 20,
  "boostRecentSearch": false
}

Search Examples

Local Database Search:

rss-viewer search "React 19" --limit 10
rss-viewer search "TypeScript" --author "Dan" --since "2024-01-01"

Web Search with Discovery:

# Use agent's built-in search (default)
rss-viewer discover-search "micro-frontends" --auto-add --read

# Use Exa API (requires EXA_API_KEY)
export EXA_API_KEY="your-api-key"
rss-viewer discover-search "WebGPU" \
  --provider exa \
  --max-results 5 \
  --category Development \
  --auto-add \
  --read \
  --limit 20

License

MIT