🐊 Gator

An RSS feed aggregator for your terminal

Quick Start • Features • Commands • Configuration

---

🎬 Demo

$ gator register alice
User `alice` registered successfully

$ gator addfeed "Go Blog" "https://go.dev/blog/feed.atom"
FEED ADDED and FOLLOWED

$ gator browse 3
Found 3 posts for user alice:
Title: Go 1.22 Released
URL: https://go.dev/blog/go1.22
Published: 2024-02-06
---

---

⚡ Quick Start

Prerequisites: Go 1.21+ and PostgreSQL

1️⃣ Set up the database

# Create database
sudo -u postgres createdb gator

# Install Goose & run migrations
go install github.com/pressly/goose/v3/cmd/goose@latest
git clone https://github.com/ifeanyibatman/Gator.git && cd Gator
goose -dir sql/schema postgres "postgres://postgres:postgres@localhost:5432/gator" up

2️⃣ Create config file

cat > ~/.gatorconfig.json << 'EOF'
{
  "db_url": "postgres://postgres:postgres@localhost:5432/gator?sslmode=disable"
}
EOF

⚠️ Edit the connection string if your PostgreSQL username/password differs from postgres:postgres

3️⃣ Install & run

go install github.com/ifeanyibatman/gator@latest
gator register yourname
gator addfeed "Hacker News" "https://hnrss.org/frontpage"
gator agg 5m &    # Start aggregating in background
gator browse 10   # View posts

---

✨ Features

Feature	Description
📡 Multi-Feed Tracking	Follow unlimited RSS/Atom feeds
🔄 Background Aggregation	Auto-fetch posts at configurable intervals
👥 Multi-User	Shared installation with per-user follows
🔍 Browse	View latest posts with optional verbose mode
⚡ Lightweight	Single binary, minimal dependencies

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         CLI (main.go)                       │
├─────────────────────────────────────────────────────────────┤
│  Commands: register │ login │ addfeed │ follow │ browse    │
└────────────────────────────┬────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
              ▼                             ▼
    ┌─────────────────┐          ┌─────────────────┐
    │   Config File   │          │   PostgreSQL    │
    │ ~/.gatorconfig  │          │   (gator db)    │
    └─────────────────┘          └─────────────────┘
                                         │
                    ┌────────────────────┼────────────────────┐
                    │                    │                    │
                    ▼                    ▼                    ▼
              ┌──────────┐        ┌──────────┐        ┌──────────┐
              │  users   │◄──────►│  feeds   │◄──────►│  posts   │
              └──────────┘        └──────────┘        └──────────┘
                    │                    │
                    └────────┬───────────┘
                             ▼
                    ┌─────────────────┐
                    │  feed_follows   │
                    └─────────────────┘

---

📖 Commands

User Management

Command	Usage	Description
register	gator register <name>	Create new user & log in
login	gator login <name>	Switch to existing user
users	gator users	List all users (★ = current)

Feed Management

Command	Usage	Description
addfeed	gator addfeed "<name>" "<url>"	Add & auto-follow feed
feeds	gator feeds	List all available feeds
follow	gator follow "<url>"	Follow existing feed
following	gator following	List your followed feeds
unfollow	gator unfollow "<url>"	Stop following feed

Reading & Aggregating

Command	Usage	Description
agg	gator agg <interval>	Fetch feeds continuously (e.g., 30s, 5m, 1h)
browse	gator browse [limit] [--verbose]	View latest posts (default: 2)

Admin

Command	Usage	Description
reset	gator reset	⚠️ Delete all users & data

---

⚙️ Configuration

Config file: ~/.gatorconfig.json

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

Connection String Format

postgres://USERNAME:PASSWORD@HOST:PORT/DATABASE?sslmode=disable
         └────┬────┘└───┬───┘ └─┬─┘└─┬─┘└───┬───┘
              │         │       │    │      └── Your database name
              │         │       │    └── Default: 5432
              │         │       └── Default: localhost
              │         └── Your PostgreSQL password
              └── Your PostgreSQL username

Common connection strings:

# Default postgres user (no password)
postgres://postgres:@localhost:5432/gator?sslmode=disable

# With password
postgres://postgres:mypassword@localhost:5432/gator?sslmode=disable

# Custom user
postgres://gatoruser:secretpass@localhost:5432/gator?sslmode=disable

---

🔧 Troubleshooting

❌ "connection refused" error

PostgreSQL isn't running. Start it:

sudo systemctl start postgresql

❌ "password authentication failed"

Wrong credentials in your connection string. Verify your PostgreSQL password:

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'newpassword';"

Then update ~/.gatorconfig.json.

❌ "relation does not exist"

Migrations haven't run. Run them:

goose -dir sql/schema postgres "YOUR_CONNECTION_STRING" up

❌ "no such file: .gatorconfig.json"

Create the config file:

echo '{"db_url": "postgres://postgres:@localhost:5432/gator?sslmode=disable"}' > ~/.gatorconfig.json

---

🛠️ Development

# Clone
git clone https://github.com/ifeanyibatman/Gator.git
cd Gator

# Install dependencies
go mod download

# Run locally
go run . register testuser

# Build
go build -o gator .

Tech Stack

• Language: Go
• Database: PostgreSQL
• SQL Generator: SQLC
• Migrations: Goose

---

📄 License

MIT © ifeanyiBatman

---

_{Built with ❤️ and Go}