Gator 🐊

Gator (because aggreGATOR) is a powerful Command Line Interface (CLI) tool built in Go that allows you to aggregate, track, and read your favorite content from across the internet directly from your terminal.

What is Gator?

RSS feeds are a standard way for websites to publish frequent updates to their content. Gator aggregates these feeds, making it easy to keep up with your favorite blogs, news sites, podcasts, and more, all in one centralized place.

Key Features

• Feed Management: Add RSS feeds from across the internet to your collection.
• Persistent Storage: Store all collected posts and data in a PostgreSQL database.
• Follow/Unfollow System: Multi-user support allows you to follow and unfollow feeds added by other users.
• Terminal Reader: View clean summaries of aggregated posts directly in your terminal, complete with links to the full articles.

---

Prerequisites

Before installing and running Gator, make sure you have the following dependencies installed on your system:

• Go: Version 1.22+ is required. (Install Go)
• PostgreSQL: A running Postgres instance to store feeds, users, and posts. (Install PostgreSQL)

---

Installation

You can install the gator CLI directly using the go install command. This will download, compile, and install the binary into your $GOPATH/bin directory.

go install github.com/oldmanmoe/gator@latest

Note: Ensure that your $GOPATH/bin (usually ~/go/bin) is added to your system's PATH environment variable so you can run the gator command from anywhere.

---

Configuration & Setup

Gator relies on a JSON configuration file located in your home directory (~/.gatorconfig.json) to know which database to connect to and which user is currently logged in.

1. Create the Config File

Create a file named .gatorconfig.json in your home directory and add your PostgreSQL connection string:

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

2. Initialize the Database

Ensure you have created a PostgreSQL database that matches your connection string:

createdb gator

Make sure your database schema and migrations are applied before running the CLI.

---

Usage & Commands

Once configured, run commands using the gator keyword. Here is the complete list of available commands:

Account Management

• register: Create a new user account in the system. This will automatically log you in as that user.

  gator register <username>

• login: Switch between existing users in the configuration file.

  gator login <username>

• users: List all registered users in the database. The currently logged-in user will be highlighted with an asterisk (*).

  gator users

Feed Management

• addfeed: Add a new RSS feed to the database. This command will also automatically make you follow the feed.

  gator addfeed <feed_name> <url>

• feeds: List all available RSS feeds in the database along with the name of the user who added them.

  gator feeds

Following / Unfollowing

• follow: Follow an existing RSS feed that is already in the database.

  gator follow <url>

• unfollow: Stop following a specific RSS feed.

  gator unfollow <url>

• following: List all the RSS feeds that the currently logged-in user is following.

  gator following

Aggregation & Content

• agg: Start the background worker process that actively fetches new posts from all registered RSS feeds. It accepts a time duration (e.g., 1m, 1h) to determine how frequently it pulls updates.

  gator agg <time_between_reqs>
  # Example: gator agg 1m

• browse: View the collected posts for the current user. You can pass an optional integer limit to restrict the number of posts displayed (defaults to 2).

  gator browse <optional_limit>
  # Example: gator browse 10

---

License

This project is open-source and available under the MIT License.