go-gator

An RSS feed aggregator CLI written in Go.

Track your favorite RSS feeds, aggregate their posts, and browse the latest articles right from your terminal.

Prerequisites

Before you can run go-gator, you'll need the following installed on your machine:

• Go 1.25 or later — the project is built with modern Go tooling. Install it from go.dev/dl or via your package manager.
• PostgreSQL — go-gator stores users, feeds, and posts in a Postgres database. Install it from postgresql.org or via your package manager (e.g. brew install postgresql@16 on macOS).

Installation

Install the go-gator CLI directly with go install:

go install github.com/geneowak/go-gator@latest

This downloads and builds the binary into your Go bin directory ($GOPATH/bin or $HOME/go/bin). Make sure that directory is on your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Then verify the install:

go-gator

You should see the usage message (not enough args were provided). Alternatively, you can clone the repo and build from source:

git clone https://github.com/geneowak/go-gator.git
cd go-gator
go build -o go-gator .

Database Setup

go-gator needs a PostgreSQL database to store data. First, create a database:

createdb gator

Then apply the schema migrations in sql/schema/ in order:

psql -d gator -f sql/schema/001_create_users_table.sql
psql -d gator -f sql/schema/002_create_feeds_table.sql
psql -d gator -f sql/schema/003_create_feed_follows_table.sql
psql -d gator -f sql/schema/004_add_last_fetched_at_to_feeds_table.sql
psql -d gator -f sql/schema/005_create_posts_table.sql

Configuration

go-gator reads its configuration from a file named .gatorconfig.json in your home directory. Create it with the connection string for your Postgres database:

cat > ~/.gatorconfig.json <<EOF
{
  "db_url": "postgres://postgres:postgres@localhost:5432/gator?sslmode=disable",
  "current_user_name": ""
}
EOF

• db_url — the connection string for your Postgres database. Update the username, password, host, and database name to match your setup.
• current_user_name — the currently logged-in user. go-gator updates this automatically when you register or login; leave it empty initially.

Usage

Here's a typical workflow:

1. Register a user (and log in):

go-gator register gene

2. Add an RSS feed and follow it (this happens automatically when you add a feed):

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

3. Start aggregating posts — agg fetches feeds continuously on a ticker. Run it in a separate terminal, or use a short interval for a one-time scrape:

go-gator agg 1m

4. Browse your latest posts from a new terminal (while agg runs):

go-gator browse

Command Reference

Command	Usage	Description
register	go-gator register <name>	Create a new user and log in as them
login	go-gator login <name>	Log in as an existing user
users	go-gator users	List all registered users (the current user is marked)
addfeed	go-gator addfeed <name> <url>	Add an RSS feed and follow it as the current user
feeds	go-gator feeds	List all feeds added by all users
follow	go-gator follow <url>	Follow an existing feed
following	go-gator following	List the feeds the current user follows
unfollow	go-gator unfollow <url>	Stop following a feed
agg	go-gator agg <duration>	Aggregate all followed feeds on a ticker (e.g. 30s, 1m, 1h)
browse	go-gator browse [limit]	Browse posts from your followed feeds (default limit 2)
reset	go-gator reset	Delete all users and data (dev convenience)

Project Structure

commands/          Command handlers for the CLI
internal/config/   Config file loading and writing
internal/database/ sqlc-generated database queries
rss/               RSS feed fetching and parsing
sql/               SQL schema migrations and query definitions
main.go            Program entry point