GitHub - jarv/newsgoat: NewsGoat is a terminal-based RSS reader

NewsGoat

NewsGoat is a terminal-based RSS reader written in Go using the bubbletea TUI framework. It's inspired by Newsbeuter/Newsboat and provides a vi-like interface for reading RSS feeds.

Why create another terminal-based RSS reader?

I’ve been using terminal-based RSS readers for about 15 years. The first program I used was Newsbeuter, but around 2017 its maintainer announced it would no longer be maintained, so I switched to its fork, Newsboat. Over time, I grew frustrated with frequent crashes and started looking for alternatives. A similar terminal-based RSS reader written in Go called nom looked interesting, but it didn’t offer the feed organization I wanted.

Meanwhile, “vibe coding” was catching on, and it seemed like a fun excuse to see how quickly I could build my own news reader in Go with exactly the features I wanted. After about a day of prompting, tweaking, and vibing through the process, here’s the result—enjoy!

Features

• Folder organization: Organize feeds into collapsible folders. Feeds can belong to multiple folders.
• Feed grouping: Feeds are grouped by the feed URL.
• Feed info: Quickly query info for every feed including cache-control, last-updated, etc. Press i to view feed info.
• Error logs: Error logs are shown directly in the UI for feed troubleshooting. Press l to view logs.
• Task management: Refresh task control separate in the app with a way to see what is queued, running and failures. Press t to view tasks.
• Flexible sorting: Option to put feeds with unread items at the top. Press c to configure.
• Auto-discovery: Automatic feed discovery when adding URLs. Press u to add a youtube link and automatically subscribe to the channel's feed.

Feed Auto Discovery

Watch individual files or directories in a GitHub/GitLab repository

It is possible to monitor individual files (or directories) in GitHub/GitLab by subscribing to that files commit history. There is first-class support for this by parsing any GitHub/GitLab link when you press u to add a URL and will subscribe to the feed. The name of the feed will be displayed as the path to the file. If GITHUB_FEED_TOKEN or GITLAB_FEED_TOKEN is set in the environment, it will use that as part of fetch for private repositories.

Youtube

Subscribe to a YouTube channel with RSS by pressing u to add a YouTube URL. This will extract the channel_id and subscribe to the channel RSS feed.

Design Principles

• Beautiful and compact: Compact design and tactful use of emojis.
• Opinionated: It was built with one (my own) preferred configuration for Newsboat in mind, it is not as configurable as the alternatives.
• A good "netizen": It follows rachelbythebay feed reader best practices.
  • sends conditional responses
  • respects cache-control and will use the local cache instead instead of a conditional response
  • sets a useful user-agent
• Database-backed with plain text editing: Feed URLs are stored in a local database but can be edited using your favorite text editor in a familiar plain text format (similar to Newsboat)
• Configuration in the UI: For what little configuration there is, it is set in the UI instead of through a configuration file

Alternatives

• The original terminal-based newsreader newsbeuter.
• Newsbeuter was archived, and I think was forked as newsboat and re-written in Rust.
• nom is a similar terminal-based news reader (also written in Go).
• feedr a different look but looks like a really nice alternative, written in Rust.

If you know of any other terminal-based RSS readers worth mentioning here please add them!

Operating Modes

NewsGoat supports three operating modes:

Standalone Mode (Default)

Run NewsGoat with a local SQLite database at ~/.config/newsgoat/newsgoat.db:

This is the default mode where everything runs locally on your machine.

Client/Server Mode

NewsGoat can run in a client/server architecture, useful for:

• Sharing a single feed database across multiple devices
• Running the server on a remote machine or home server
• Keeping feed refresh operations on the server while accessing from multiple clients

Server Mode

Start a gRPC server that manages the database and feed operations:

export NEWSGOAT_API_KEY="your-secret-api-key"
newsgoat --mode=server --server-port=50051 --db=/path/to/newsgoat.db

Options:

• --server-port: Port for the gRPC server (default: 50051)
• --db: Path to the SQLite database file (optional, defaults to ~/.config/newsgoat/newsgoat.db)
• NEWSGOAT_API_KEY: Environment variable for API authentication (required)

Client Mode

Connect to a remote NewsGoat server:

export NEWSGOAT_API_KEY="your-secret-api-key"
newsgoat --mode=client --server-url=localhost:50051

Options:

• --server-url: Address of the gRPC server (required)
• NEWSGOAT_API_KEY: Environment variable for API authentication (optional, but required if server uses authentication)

In client mode:

• No local database is needed
• All feed operations are performed on the server
• Multiple clients can connect to the same server simultaneously
• Feed refreshes happen on the server, keeping all clients in sync

Configure

NewsGoat stores feed URLs in a local SQLite database (~/.config/newsgoat/newsgoat.db by default). You can add and manage feeds through the UI (see "Add Feed URLs" section below).

Development

Setup

1. Install mise for tool version management
2. Clone the repository
3. Enable git hooks:

This will configure git to run the linter before each commit.

Building

mise run build    # Build the binary
go run .          # Run the application

Linting

The project uses golangci-lint for code quality:

mise run lint     # Run the linter

The linter runs automatically on every commit via a pre-commit hook. To bypass temporarily (not recommended):

Install

Quick Install (Recommended)

Install with a single command (macOS and Linux):

curl -sSL https://raw.githubusercontent.com/jarv/newsgoat/main/install.sh | bash

This will automatically detect your OS and architecture and install the latest version to /usr/local/bin.

Manual Install

Download the latest release for your platform from the releases page:

macOS (Apple Silicon / Intel)

# Apple Silicon
curl -L https://github.com/jarv/newsgoat/releases/latest/download/newsgoat-darwin-arm64 -o newsgoat
chmod +x newsgoat
sudo mv newsgoat /usr/local/bin/

curl -L https://github.com/jarv/newsgoat/releases/latest/download/newsgoat-darwin-amd64 -o newsgoat
chmod +x newsgoat
sudo mv newsgoat /usr/local/bin/

Linux (amd64 / arm64)

curl -L https://github.com/jarv/newsgoat/releases/latest/download/newsgoat-linux-amd64 -o newsgoat
chmod +x newsgoat
sudo mv newsgoat /usr/local/bin/

curl -L https://github.com/jarv/newsgoat/releases/latest/download/newsgoat-linux-arm64 -o newsgoat
chmod +x newsgoat
sudo mv newsgoat /usr/local/bin/

Add Feed URLs

There are three ways to add feed URLs to NewsGoat:

1. Via Command Line

Add a feed URL directly from the command line with automatic feed discovery:

NewsGoat will automatically discover the RSS/Atom feed URL from the provided URL. For example:

• newsgoat add https://example.com will find the feed link in the page
• newsgoat add https://youtube.com/@channel will discover the YouTube RSS feed

2. In the Application (Interactive)

Press u in the feed list view to open an interactive prompt where you can:

• Type or paste a URL (optionally followed by folders)
• Format: <url> or <url> folder1,folder2 or <url> "folder with spaces",folder3
• Press Enter to add (with automatic feed discovery)
• Press Esc to cancel

Examples:

• https://example.com Tech News
• https://youtube.com/@channel Tech News,YouTube
• https://example.com "My Folder",Tech

3. Edit URLs in Your Editor

Press U (Shift+U) in the feed list view to open a temporary file in your $EDITOR with your current feeds.

How it works:

• NewsGoat creates a temporary file populated with all your current feeds
• Edit the file in your preferred editor (set via $EDITOR environment variable)
• When you save and exit, NewsGoat updates the database with your changes
• The temporary file is automatically deleted after syncing

File format:

• Add one feed URL per line
• Optionally add folders after the URL: <url> folder1,folder2
• Use quotes for folder names with spaces: <url> "folder name",otherfolder
• Lines starting with # are treated as comments
• Feeds not in the file will be hidden (but not deleted from the database)

Example format:

# Feeds can have folders! Format: <url> folder1,folder2
# Use quotes for folder names with spaces: <url> "folder name",otherfolder

# Tech News
https://www.theverge.com/rss/index.xml Tech News
https://feeds.feedburner.com/TechCrunch/ Tech News,Startups
https://www.wired.com/feed/rss Tech News

# Science feeds
https://www.sciencedaily.com/rss/top/science.xml Science
https://www.nasa.gov/rss/dyn/breaking_news.rss Science,Space

# Feeds with spaces in folder names
https://www.popularmechanics.com/rss/all.xml/ "DIY & Tech"

# Feeds without folders
https://example.com/feed

Organizing Feeds with Folders

NewsGoat supports organizing feeds into folders:

• Multiple folders: Feeds can belong to multiple folders and will appear under each one
• Collapsible: Press Enter on a folder to expand/collapse its contents
• Visual hierarchy: Feeds under folders are displayed with a vertical bar (│) for easy identification
• Folder operations:
  • Press r on a folder to refresh all feeds in that folder
  • Press A on a folder to mark all items in that folder as read
• Sorting: When "Unread on Top" is enabled:
  • Unread feeds without folders appear at the very top
  • Within folders, unread feeds appear before read feeds

Searching Feeds and Articles

NewsGoat provides two search modes with case-insensitive text matching:

Search Modes

• Global Search (/): Searches across multiple fields

  • Feed List View: Searches all feed content
  • Item List View: Searches all feed content across feed items

• Title Search (Ctrl+F): Searches only titles

  • Feed List View: Searches feed titles only
  • Item List View: Searches item titles only

Using Search

1. Press / or Ctrl+F to start searching
2. Type your search query (case-insensitive text matching)
3. Switch between modes anytime by pressing / or Ctrl+F
4. Press Enter to exit search mode and keep results
5. Press Esc to cancel and restore original view

Search filters results in real-time as you type, making it easy to find specific feeds or articles quickly.

Keys

Global (Available in All Views)

Feed List View

Item List View (Articles in a Feed)

Article View

Tasks View

Log View

Settings View

Status Icons