Gator

A CLI RSS feed aggregator. Register an account, subscribe to feeds, run the aggregator in the background, and browse the latest posts — all from your terminal.

Prerequisites

• Go 1.22 or later
• PostgreSQL running locally (or accessible remotely)

Installation

go install github.com/raphaelcdsouza/gator@latest

This will download, compile, and place the gator binary in your $GOPATH/bin directory. Make sure that directory is on your PATH.

Configuration

Gator reads its configuration from ~/.gatorconfig.json. Create that file with your PostgreSQL connection string:

{
  "db_url": "postgres://username:password@localhost:5432/gator?sslmode=disable"
}

Replace username, password, and gator (the database name) with your own values. The database must already exist before running the program.

Running migrations

The schema is managed with Goose. From the repo root, run:

goose -dir sql/schema postgres "postgres://username:password@localhost:5432/gator?sslmode=disable" up

Usage

User management

Register a new user and set them as the current user:

gator register alice

Log in as an existing user:

gator login alice

List all registered users (the current user is marked with *):

gator users

Feed management

Add a new RSS feed and automatically follow it:

gator addfeed "Hacker News" https://news.ycombinator.com/rss

List all feeds that have been added by any user:

gator feeds

Follow an existing feed by its URL:

gator follow https://news.ycombinator.com/rss

Unfollow a feed:

gator unfollow https://news.ycombinator.com/rss

List all feeds you are currently following:

gator following

Aggregation

Start the aggregator. It fetches new posts from all feeds on a repeating interval:

gator agg 30s

The interval accepts any Go duration string: 30s, 1m, 5m, etc. Keep this running in a separate terminal while you browse posts.

Browsing posts

Display the latest posts from feeds you follow (defaults to 2):

gator browse

Specify how many posts to show:

gator browse 10