Gator

A command-line RSS feed aggregator. Add feeds, follow them, and browse the latest posts — all from your terminal.

Prerequisites

• Node.js (v18+)
• PostgreSQL database

Installation

npm install

Configuration

Gator reads its config from a JSON file located at ~/.gatorconfig.json in your home directory. Create it before running the CLI:

{
  "db_url": "postgres://user:password@localhost:5432/gator",
  "current_user_name": ""
}

Replace db_url with your actual PostgreSQL connection string. You can leave current_user_name empty — it will be set automatically when you register or login.

Database Setup

Run the migrations to create the required tables:

# Run the npx drizzle-kit generate command to generate the migration files based on our current schema state. These files are created in the directory you specified in the out field of drizzle.config.ts.
`npx drizzle-kit generate`

# If everything looks like it should, run the migration.
`npx drizzle-kit migrate`

Running the CLI

npm start -- <command> [args]

Commands

User Management

Command	Usage	Description
register	npm start -- register <name>	Create a new user and log in as them
login	npm start -- login <name>	Switch to an existing user
users	npm start -- users	List all registered users
reset	npm start -- reset	Delete all users and data (destructive!)

Feed Management

Command	Usage	Description
addfeed	npm start -- addfeed <name> <url>	Add a new RSS feed and follow it (requires login)
feeds	npm start -- feeds	List all available feeds
follow	npm start -- follow <url>	Follow an existing feed by URL (requires login)
following	npm start -- following	List feeds you are currently following (requires login)
unfollow	npm start -- unfollow <url>	Unfollow a feed by URL (requires login)

Aggregation & Browsing

Command	Usage	Description
agg	npm start -- agg <interval>	Start the feed aggregator, polling on the given interval (e.g. 30s, 5m, 1h)
browse	npm start -- browse [limit]	Browse the latest posts from your followed feeds. Default limit is 2

Example Workflow

# 1. Register a new user
npm start -- register alice

# 2. Add an RSS feed
npm start -- addfeed "Boot.dev Blog" https://blog.boot.dev/index.xml

# 3. Start aggregating posts (runs until Ctrl+C)
npm start -- agg 30s

# 4. Browse the latest posts
npm start -- browse 10