Lib.rs

      ██████╗██████╗██████╗██████╗  ██████╗
      ██╔═══╝██╔═══╝██╔═══╝██╔══██╗██╔═══██╗
      █████╗ █████╗ █████╗ ██║  ██║██║   ██║
      ██╔══╝ ██╔══╝ ██╔══╝ ██║  ██║██║   ██║
      ██║    ██████╗██████╗██████╔╝╚██████╔╝
      ╚═╝    ╚═════╝╚═════╝╚═════╝  ╚═════╝ 
  

A beautiful, fast, and modern terminal RSS reader built with Rust.
Think Reeder meets the command line.

📸 Screenshots

Main View

Three-panel layout: feeds, articles, and content preview with Dracula theme

Search

Real-time search across all your feeds

Add Feed

Auto-discover RSS/Atom feeds from any URL

✨ Features

🚀 Installation

Homebrew (macOS/Linux)

brew install ricardodantas/tap/feedo

Cargo (All Platforms)

cargo install feedo

From Source

# Clone the repository
git clone https://github.com/ricardodantas/feedo.git
cd feedo

# Build with optimizations
cargo build --release

# Run it!
./target/release/feedo

Pre-built Binaries

Download from GitHub Releases — available for Linux (x64, ARM64, musl), macOS (Intel, Apple Silicon), and Windows.

Requirements

• A terminal with Unicode support
• That's it!

📖 Usage

Basic Commands

# Launch the TUI
feedo

# Import feeds from another reader
feedo --import subscriptions.opml

# Backup your feeds
feedo --export backup.opml

# Show help
feedo --help

Sync Commands

# Configure sync with your server
feedo sync login <server> <username> <password>

# Check sync status
feedo sync status

# Run full sync (import feeds + sync read states)
feedo sync

Tip: Once configured, press S in the TUI to sync without leaving the app!

Adding Feeds

Press n in the app to add a new feed. Just paste any URL — Feedo will auto-discover the RSS/Atom feed:

┌─ ➕ Add Feed ──────────────────────────────────────────┐
│ 🔗 https://blog.rust-lang.org│                        │
└───────────────────────────────────────────────────────┘

Feedo tries:

1. The URL directly (if it's already a feed)
2. <link rel="alternate"> tags in HTML
3. Common paths like /feed, /rss, /atom.xml

First Run

On first launch, Feedo creates a default configuration with some starter feeds:

• Tech: Hacker News, Lobsters
• News: BBC World

Feel free to modify ~/.config/feedo/config.json to add your own!

⌨️ Keybindings

Navigation

Actions

Share Mode

Add Feed Mode

Search Mode

Theme Picker

⚙️ Configuration

Config Location

Feedo uses ~/.config/feedo/ on all platforms for consistency:

Example Configuration

{
  "folders": [
    {
      "name": "Tech",
      "icon": "💻",
      "expanded": true,
      "feeds": [
        {
          "name": "Hacker News",
          "url": "https://hnrss.org/frontpage"
        },
        {
          "name": "Lobsters",
          "url": "https://lobste.rs/rss"
        },
        {
          "name": "This Week in Rust",
          "url": "https://this-week-in-rust.org/rss.xml"
        }
      ]
    },
    {
      "name": "News",
      "icon": "📰",
      "expanded": false,
      "feeds": [
        {
          "name": "BBC World",
          "url": "https://feeds.bbci.co.uk/news/world/rss.xml"
        }
      ]
    }
  ],
  "feeds": [
    {
      "name": "xkcd",
      "url": "https://xkcd.com/rss.xml"
    }
  ],
  "theme": {
    "name": "dracula"
  },
  "refresh_interval": 30
}

Offline Mode & Cache

Feedo automatically caches all articles for offline reading:

How it works:

• Articles are cached after each successful fetch
• Read/unread states persist between sessions
• When offline, you can still browse all previously fetched articles
• Cache is updated on every refresh and saved on exit

No configuration needed — offline mode works automatically!

☁️ Cloud Sync

Feedo supports syncing with RSS servers that implement the Google Reader API.

✅ Tested & Working

⚠️ Not Currently Supported

Quick Start: FreshRSS (Docker)

# 1. Spin up FreshRSS
podman run -d --name freshrss -p 8080:80 freshrss/freshrss
# Or: docker run -d --name freshrss -p 8080:80 freshrss/freshrss

# 2. Visit http://localhost:8080 and complete the setup wizard
#    - Create your admin account
#    - Choose SQLite for simplicity

# 3. Enable API access:
#    Settings → Authentication → ☑ Allow API access

# 4. Set API password:
#    Settings → Profile → API password (can be different from login password)

# 5. Connect Feedo
feedo sync login http://localhost:8080/api/greader.php your_user your_api_password
feedo sync status  # Verify connection
feedo sync         # Run first sync

Quick Start: Miniflux (Docker)

# 1. Spin up Miniflux with PostgreSQL
podman run -d --name miniflux-db -e POSTGRES_USER=miniflux \
  -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=miniflux postgres:15

podman run -d --name miniflux -p 8080:8080 \
  -e DATABASE_URL="postgres://miniflux:secret@miniflux-db/miniflux?sslmode=disable" \
  -e RUN_MIGRATIONS=1 \
  -e CREATE_ADMIN=1 \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=admin123 \
  miniflux/miniflux:latest

# Or with docker-compose (recommended for production)

# 2. Visit http://localhost:8080 and login with admin/admin123

# 3. Enable Fever API (used for Google Reader compatibility):
#    Settings → Integrations → Fever → Enable & set password

# 4. Connect Feedo (note: Miniflux uses /v1/ endpoint)
feedo sync login http://localhost:8080/v1/ admin your_fever_password
feedo sync status
feedo sync

Tip: For production, see FreshRSS Docker docs or Miniflux installation guide.

Setup

# Configure your sync server
feedo sync login https://freshrss.example.com/api/greader.php myuser mypassword

# Verify connection
feedo sync status

What syncs?

Running Sync

From CLI:

feedo sync

From TUI:
Press S (shift+s) — the status bar shows a ☁️ indicator when sync is configured.

Config Example

After running feedo sync login, your config will include:

{
  "sync": {
    "provider": "freshrss",
    "server": "https://freshrss.example.com/api/greader.php",
    "username": "myuser",
    "password": "mypassword"
  }
}

Note: For security, consider using an API password or app-specific password if your service supports it.

Theme Colors

Feedo comes with 15 popular themes from the terminal/editor world:

Example config:

{
  "theme": {
    "name": "catppuccin-mocha"
  }
}

| orange | 🟠 Energetic | | pink | 🩷 Soft and playful |

🏗️ Architecture

src/
├── main.rs              # Entry point, CLI handling
├── lib.rs               # Library root, public API
│
├── app/                 # Application core
│   └── mod.rs           # App state, event loop, orchestration
│
├── config/              # Configuration management
│   ├── mod.rs           # Module exports
│   └── data.rs          # Config structs, load/save logic
│
├── feed/                # Feed management
│   ├── mod.rs           # Module exports  
│   ├── item.rs          # FeedItem struct
│   ├── manager.rs       # FeedManager, Folder, async fetching
│   └── parser.rs        # RSS/Atom parsing with feed-rs
│
├── opml/                # OPML import/export
│   └── mod.rs           # Full OPML 2.0 support
│
├── theme/               # Theming system
│   └── mod.rs           # AccentColor, Theme configuration
│
└── ui/                  # Terminal UI
    ├── mod.rs           # Module exports
    ├── state.rs         # UI state machine
    ├── input.rs         # Keyboard input handling
    ├── render.rs        # Rendering logic, layouts
    └── widgets/         # Custom ratatui widgets

Design Principles

• Separation of Concerns — Each module has a single responsibility
• Async by Default — Network operations never block the UI
• Immutable State — UI state is explicit and predictable
• Error Propagation — Errors bubble up with context via color-eyre
• Zero Unsafe — Memory safety guaranteed by the compiler

🗺️ Roadmap

• Feed Discovery — Auto-detect RSS from any URL ✅
• Offline Mode — Cache articles for reading without internet ✅
• Cloud Sync — Sync with FreshRSS, Miniflux via Google Reader API ✅
• Custom Keybindings — Full key remapping
• Notifications — Desktop alerts for new articles

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

📄 License

MIT © Ricardo Dantas

Made with ❤️ and 🦀

(◕ᴥ◕) Happy reading!