🐊 Gator — RSS Feed Aggregator CLI

Gator is a command-line RSS feed aggregator built with Go and PostgreSQL. Subscribe to your favorite RSS feeds, automatically scrape new posts, and browse them right from your terminal! 🚀

---

📋 Prerequisites

Before you get started, make sure you have the following installed on your machine:

🐘 PostgreSQL

You'll need a running PostgreSQL instance. Gator uses it to store users, feeds, and posts.

• macOS: brew install postgresql@16 && brew services start postgresql@16
• Linux (Debian/Ubuntu): sudo apt install postgresql && sudo systemctl start postgresql
• Windows: Download from postgresql.org

Once installed, create a database for Gator:

CREATE DATABASE gator;

🐹 Go

You'll need Go 1.25+ installed.

• Download from go.dev/dl
• Verify your installation: go version

🪿 Goose (Database Migrations)

Gator uses Goose to manage database migrations.

go install github.com/pressly/goose/v3/cmd/goose@latest

---

🔧 Installation

Install the Gator CLI directly with go install:

go install github.com/kerkox/gator@latest

This will compile and install the gator binary into your $GOPATH/bin directory. Make sure that directory is in your PATH:

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

💡 Tip: Add the line above to your ~/.bashrc, ~/.zshrc, or shell config to make it permanent.

---

🗄️ Database Setup

Run the Goose migrations to create the required tables:

cd /path/to/gator
goose postgres "postgres://your_user:your_password@localhost:5432/gator?sslmode=disable" up

This will create the users, feeds, feed_follows, and posts tables. ✅

---

⚙️ Configuration

Gator reads its configuration from a JSON file located at ~/.gatorconfig.json. Create it manually:

{
  "db_url": "postgres://your_user:your_password@localhost:5432/gator?sslmode=disable"
}

Field	Description
db_url	PostgreSQL connection string (required)
current_user_name	Active user — set automatically by register/login

🔐 Note: Replace your_user and your_password with your actual PostgreSQL credentials.

---

🚀 Usage

gator <command> [args...]

👤 User Management

Command	Description
gator register <name>	Create a new user and set as active 🆕
gator login <name>	Switch to an existing user 🔑
gator users	List all registered users 📋

gator register alice
# ✅ User "alice" created and set as current user

gator login alice
# 🔑 Switched to user "alice"

📡 Feed Management

Command	Description
gator addfeed <name> <url>	Add a new RSS feed and auto-follow it 📥
gator feeds	List all available feeds 📋
gator follow <feed_url>	Subscribe to an existing feed ➕
gator following	List your subscribed feeds 👀
gator unfollow <feed_url>	Unsubscribe from a feed ❌

gator addfeed "Go Blog" https://blog.golang.org/feed.atom
# 📥 Feed "Go Blog" added and followed!

gator feeds
# 📋 Lists all feeds with their creators

gator following
# 👀 Shows all feeds you're subscribed to

🔄 Aggregation

Start the feed scraper to automatically fetch new posts at a given interval:

gator agg 1m
# 🔄 Scraping feeds every 1 minute...

The duration accepts Go duration strings: 10s, 1m, 1h, etc.

💡 Tip: Run agg in a separate terminal window so it continuously fetches new posts in the background!

📖 Browsing Posts

View posts from your subscribed feeds:

gator browse
# 📖 Shows the 2 most recent posts (default)

gator browse 10
# 📖 Shows the 10 most recent posts

🧹 Reset

Delete all users (and cascade-delete all related data):

gator reset
# ⚠️ All users, feeds, follows, and posts deleted!

---

🏗️ Project Structure

gator/
├── main.go                    # Entry point
├── commands.go                # Command dispatcher
├── handler_*.go               # Command handlers
├── middleware_loggedIn.go     # Auth middleware
├── rss_feed.go                # RSS XML parser
├── state.go                   # App state (db + config)
├── internal/
│   ├── config/                # Config file reader/writer
│   └── database/              # SQLc-generated database layer
└── sql/
    ├── schema/                # Goose migration files
    └── queries/               # SQLc query definitions

---

📜 License

This project was built as part of the Boot.dev backend developer curriculum. 🎓

Happy aggregating! 🐊✨