paperboy

Rust CLI RSS/Atom feed reader built for LLMs. Organize feeds into topics, fetch latest articles, render them as markdown, and track read state.

Install

cargo install --path .

Usage

Output format

All commands support --format <md|json|plain> (default: md).

# Markdown table (default)
paperboy latest rust

# JSON for programmatic consumption
paperboy --format json latest rust

# Plain pipe-delimited text
paperboy --format plain latest rust

Manage topics

# Add a feed to a topic (creates topic if it doesn't exist)
paperboy topic add rust https://blog.rust-lang.org/feed.xml
paperboy topic add rust https://this-week-in-rust.org/atom.xml
paperboy topic add sailing https://www.sailingworld.com/feed/

# List all topics and feeds
paperboy topic list

# Remove a specific feed from a topic
paperboy topic remove-feed rust https://blog.rust-lang.org/feed.xml

# Remove a topic entirely
paperboy topic remove sailing

Fetch latest articles

# Fetch and list latest articles across all topics
paperboy latest

# Fetch latest for a specific topic
paperboy latest rust

# Only show unread articles
paperboy latest --unseen

# Limit results
paperboy latest -n 10

Render articles as markdown

# Fetch one article by ID
paperboy fetch abc12345

# Fetch multiple articles
paperboy fetch abc12345,def67890

Articles are automatically marked as read when fetched.

Search articles

# Search across all topics
paperboy search "async runtime"

# Search within a specific topic
paperboy search "async runtime" --topic rust

Import / Export OPML

# Import feeds from an OPML file (categories become topics)
paperboy import feeds.opml

# Set a custom default topic for uncategorized feeds
paperboy import feeds.opml --default-topic misc

# Export all topics/feeds as OPML
paperboy export > my-feeds.opml

OPML categories are converted to lowercase topic names. Feeds without a category go into "uncategorized" (or the --default-topic value). Importing is idempotent — duplicate feeds are skipped.

Summary

# Overview of topics, feeds, and article counts
paperboy summary

# As JSON
paperboy --format json summary

Read state management

# Mark articles as read
paperboy read abc12345,def67890

# Mark articles as unread
paperboy unread abc12345

State is stored in ~/.cache/paperboy/state.json. Use --state-file <path> to override.

Concepts

• Topics — named groups of RSS/Atom feeds (e.g. "rust", "sailing", "music")
• Articles — individual feed entries, tracked by short ID
• Read state — articles are marked read when fetched; can be toggled manually
• Markdown output — article HTML is converted to markdown for LLM consumption
• Output formats — md (markdown tables), json (structured), plain (pipe-delimited)

License

MIT