Gator

Gator is a high-performance, command-line RSS feed aggregator written in Go and backed by a PostgreSQL database. It fetches articles and blog posts from feeds you follow in a continuous, non-blocking background loop and lets you browse them directly in your terminal.

---

Prerequisites

To compile and run Gator, you need the following dependencies installed on your system:

1. Go Toolchain: Go v1.26 or higher.
2. PostgreSQL: PostgreSQL server active and accessible (listening on your local or remote port).

---

Installation

Since Go compiles to a single static binary, you can install the gator executable directly into your $GOPATH/bin directory by running:

# Clone the repository
git clone https://github.com/archangelopolis-debug/gator.git
cd gator

# Install the statically compiled binary
go install

Make sure your $GOPATH/bin (typically ~/go/bin) is added to your system's PATH environment variable so you can invoke gator from any folder.

---

Configuration

Gator expects a JSON configuration file located at ~/.gatorconfig.json containing the database connection URL and the currently logged-in user.

Create this file at ~/.gatorconfig.json:

{
  "db_url": "postgres://postgres:postgres@localhost:5433/gator?sslmode=disable",
  "current_user_name": "lane"
}

Note: Adjust the port (e.g., 5433 or 5432) and credentials to match your PostgreSQL setup.

---

Database Migrations

Gator uses Goose for database schema migrations. If you have Goose installed, you can apply migrations from the schema folder:

cd sql/schema
goose postgres "postgres://postgres:postgres@localhost:5433/gator?sslmode=disable" up

---

Commands Reference

Here are the main commands available in Gator:

User Management

• Register a user:

  gator register <username>

• Switch active user:

  gator login <username>

• List all registered users:

  gator users

Feed Management

• Register a feed:

  gator addfeed <feed_name> <feed_url>

• List all feeds in the system:

  gator feeds

Subscription Management

• Follow a feed:

  gator follow <feed_url>

• List followed feeds:

  gator following

• Unfollow a feed:

  gator unfollow <feed_url>

Scraper & Aggregator

• Start the long-running collection loop:

  gator agg <time_between_requests>

  Example: gator agg 1m or gator agg 30s Leave this command running in a background terminal to continually populate the database. Use Ctrl+C to terminate safely.

Browsing Posts

• Browse posts from followed feeds:

  gator browse [optional_limit]

  Example: gator browse 5 (defaults to 2 if limit is omitted)

Maintenance

• Truncate all users and feeds:

  gator reset