Gator

A simple CLI RSS reader written in Go. It lets you register/login a user, add RSS feeds, follow/unfollow feeds, run a background-style aggregator to fetch posts, and browse your latest posts.

Prerequisites

• Go 1.21+ installed
• PostgreSQL 13+ running and reachable

Install the CLI

You can install the CLI directly with go install (this produces a statically compiled binary you can run without the Go toolchain):

# Replace with your own module path if you fork this repo
wsl.exe -e bash -lc "go install"

This installs the gator binary to your Go bin directory (typically ~/go/bin on Linux/WSL). Ensure that directory is on your PATH.

For development, you can also run directly from source:

wsl.exe -e bash -lc "go run ."

Note: go run . is for development; gator (built via go build or go install) is for production use.

Database setup

1. Create a PostgreSQL database and user. For example:

# example, customize to your environment
psql -U postgres -c "CREATE DATABASE gator;"

2. Set a DATABASE_URL (or DB_URL) environment variable pointing to your database, for example:

# Example DSN format for lib/pq
export DATABASE_URL="postgres://user:password@localhost:5432/gator?sslmode=disable"

3. Apply the migrations in sql/schema using your migration tool of choice, or manually:

• The schema uses Goose-style up files but can be applied in order:
  • 001_users.sql
  • 002_feeds.sql
  • 003_feed_follows.sql
  • 004_feeds.sql (adds last_fetched_at)
  • 005_posts.sql

If you use goose, you can adapt commands to your setup; otherwise run the SQL files sequentially.

4. Generate SQL code (only needed after you change SQL under sql/):

wsl.exe -e bash -lc "sqlc generate"

Configuration

Gator looks for a JSON config file at ~/.gatorconfig.json. It can also read the database URL from DATABASE_URL or DB_URL environment variables.

Example config file:

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

• db_url: Your Postgres DSN (optional if you set DATABASE_URL/DB_URL in the environment)
• current_user_name: Will be set by gator login <username>

Build

Build a production binary:

wsl.exe -e bash -lc "go build -o gator"

After building or installing, you can run the binary directly without the Go toolchain present on the machine.

Commands

• gator register <username>: Create a new user and set it as current
• gator login <username>: Set current user (must already exist)
• gator users: List all users (current indicated)
• gator reset: Reset the users DB (dev utility)
• gator addfeed <name> <url>: Create a feed owned by current user and auto-follow it
• gator feeds: List all feeds and the owning user
• gator follow <feed-url>: Follow an existing feed by URL
• gator following: List feeds the current user follows
• gator unfollow <feed-url>: Unfollow a feed by URL
• gator agg <duration>: Run aggregator loop (e.g., agg 1m), fetching the oldest feed next and saving posts
• gator browse [limit]: Show newest posts for the current user (default limit 2)

Running the aggregator

The aggregator chooses the next feed to fetch based on last_fetched_at and persists posts from the RSS feed. Duplicate posts (by URL) are ignored.

Example:

# fetch every minute
wsl.exe -e bash -lc "gator agg 1m"

Pushing to GitHub

You can push this repository to GitHub with the following steps:

# initialize git if needed
wsl.exe -e bash -lc "git init && git add -A && git commit -m 'Initial commit of gator'"

# on GitHub, create a new repository (e.g., github-username/gator)
# then set your remote and push
wsl.exe -e bash -lc "git remote add origin https://github.com/<github-username>/<repo-name>.git"
wsl.exe -e bash -lc "git branch -M main && git push -u origin main"

Submit your repo link in this form:

https://github.com/<github-username>/<repo-name>

Troubleshooting

• If you see build errors about missing sqlc-generated methods, run sqlc generate.
• If the aggregator fails to fetch, ensure the feed URLs are reachable and your system has network access.
• On Windows, we recommend using WSL for building and running; commands above are formatted for a WSL shell.