gator

A command-line RSS feed aggregator written in Go. Follow feeds, collect posts in the background, and browse them from your terminal.

Español más abajo — ir a la versión en español.

---

English

What it does

gator lets multiple users register, follow RSS feeds, and continuously scrape those feeds into a PostgreSQL database. Posts are deduplicated by URL, so you can leave the aggregator running for as long as you like without piling up copies.

Prerequisites

You need two things installed before you start:

• Go 1.26.3 or newer — install instructions. The program is built and installed with the Go toolchain.
• PostgreSQL 15 or newer — install instructions. This is where feeds and posts are stored. You need a running server you can connect to.

You will also need goose to create the database tables:

go install github.com/pressly/goose/v3/cmd/goose@latest

Installing the CLI

Clone the repo and install it with go install:

git clone https://github.com/FaceNach/gator.git
cd gator
go install .

This compiles the program and drops the binary in your Go bin directory (usually ~/go/bin). The binary is named aggregator.

Make sure that directory is on your PATH, otherwise your shell won't find the command:

# bash/zsh — add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(go env GOPATH)/bin"

# fish — add to ~/.config/fish/config.fish
fish_add_path (go env GOPATH)/bin

Confirm it worked:

aggregator users

Setting up the database

Create a database for the program:

createdb gator

Then run the migrations from the sql/schema directory, passing your connection string:

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

Adjust the user, password, host, and port to match your own Postgres setup.

Setting up the config file

gator reads a JSON config file from your home directory at ~/.gatorconfig.json. Create it by hand:

{
  "connection_string": "postgres://postgres:postgres@localhost:5432/gator?sslmode=disable"
}

connection_string is the only field you need to set yourself — it's how the program connects to Postgres, and it must match the database you just migrated. Use the same credentials you used with goose.

The program adds a username_goes_here field to this file on its own the first time you register or log in. That field tracks who is currently logged in, so you don't have to manage it.

Note on sslmode=disable: this is fine for a local database. If you ever point gator at a remote Postgres server, drop that parameter so the connection is encrypted.

Usage

Register a user (this also logs you in):

aggregator register kahya

Add a feed and follow it in one step:

aggregator addfeed "TechCrunch" "https://techcrunch.com/feed/"
aggregator addfeed "Hacker News" "https://news.ycombinator.com/rss"

Start collecting posts. This is a long-running loop — the idea is to leave it in its own terminal while you use the other commands elsewhere. It takes a duration string like 30s, 1m, or 1h, and fetches one feed per tick. Press Ctrl+C to stop it:

aggregator agg 1m

Read what it collected. The limit is optional and defaults to 2:

aggregator browse 10

Commands

Command	Description
register <name>	Create a new user and log in as them
login <name>	Switch to an existing user
users	List all users, marking the current one
addfeed <name> <url>	Add a feed and follow it (must be logged in)
feeds	List every feed added by any user
follow <url>	Follow a feed that already exists
following	List the feeds you follow
unfollow <url>	Stop following a feed (must be logged in)
agg <duration>	Continuously scrape feeds every <duration>; stop with Ctrl+C
browse [limit]	Show recent posts from feeds you follow (default: 2)
reset	Delete all users (and everything belonging to them)

Careful with reset: it wipes the users table, and feeds, follows, and posts cascade away with it. There is no confirmation prompt.

Feeds to try

• TechCrunch — https://techcrunch.com/feed/
• Hacker News — https://news.ycombinator.com/rss
• Hacker News (newest) — https://hnrss.org/newest
• Wags Lane — https://www.wagslane.dev/index.xml

---

gator (Español)

Qué hace

gator te permite registrar usuarios, seguir feeds RSS, y scrapear esos feeds de forma continua hacia una base de datos PostgreSQL. Los posts se deduplican por URL, así que podés dejar el agregador corriendo todo el tiempo que quieras sin que se acumulen copias.

Requisitos previos

Necesitás dos cosas instaladas antes de empezar:

• Go 1.26.3 o superior — instrucciones de instalación. El programa se compila e instala con la toolchain de Go.
• PostgreSQL 15 o superior — instrucciones de instalación. Es donde se guardan los feeds y los posts. Necesitás un servidor corriendo al que puedas conectarte.

También vas a necesitar goose para crear las tablas:

go install github.com/pressly/goose/v3/cmd/goose@latest

Instalar la CLI

Cloná el repo e instalalo con go install:

git clone https://github.com/FaceNach/gator.git
cd gator
go install .

Esto compila el programa y deja el binario en tu directorio bin de Go (normalmente ~/go/bin). El binario se llama aggregator.

Asegurate de que ese directorio esté en tu PATH, si no tu shell no va a encontrar el comando:

# bash/zsh — agregar a ~/.bashrc o ~/.zshrc
export PATH="$PATH:$(go env GOPATH)/bin"

# fish — agregar a ~/.config/fish/config.fish
fish_add_path (go env GOPATH)/bin

Confirmá que funcionó:

aggregator users

Configurar la base de datos

Creá una base de datos para el programa:

createdb gator

Después corré las migraciones desde el directorio sql/schema, pasándole tu connection string:

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

Ajustá usuario, contraseña, host y puerto según tu instalación de Postgres.

Configurar el archivo de config

gator lee un archivo JSON de configuración desde tu directorio home, en ~/.gatorconfig.json. Crealo a mano:

{
  "connection_string": "postgres://postgres:postgres@localhost:5432/gator?sslmode=disable"
}

connection_string es el único campo que tenés que setear vos — es la forma en que el programa se conecta a Postgres, y tiene que apuntar a la base que acabás de migrar. Usá las mismas credenciales que usaste con goose.

El programa agrega solo el campo username_goes_here a este archivo la primera vez que te registrás o hacés login. Ese campo lleva la cuenta de quién está logueado, así que no tenés que tocarlo.

Nota sobre sslmode=disable: está bien para una base local. Si algún día apuntás gator a un Postgres remoto, sacá ese parámetro para que la conexión vaya encriptada.

Uso

Registrá un usuario (esto también te loguea):

aggregator register kahya

Agregá un feed y seguilo en un solo paso:

aggregator addfeed "TechCrunch" "https://techcrunch.com/feed/"
aggregator addfeed "Hacker News" "https://news.ycombinator.com/rss"

Empezá a recolectar posts. Esto es un loop infinito — la idea es dejarlo en su propia terminal mientras usás los otros comandos en otra. Toma un string de duración como 30s, 1m o 1h, y busca un feed por cada tick. Apretá Ctrl+C para frenarlo:

aggregator agg 1m

Leé lo que recolectó. El limit es opcional y por defecto es 2:

aggregator browse 10

Comandos

Comando	Descripción
register <nombre>	Crea un usuario nuevo y te loguea como él
login <nombre>	Cambia a un usuario existente
users	Lista todos los usuarios, marcando el actual
addfeed <nombre> <url>	Agrega un feed y lo sigue (requiere estar logueado)
feeds	Lista todos los feeds agregados por cualquier usuario
follow <url>	Sigue un feed que ya existe
following	Lista los feeds que seguís
unfollow <url>	Deja de seguir un feed (requiere estar logueado)
agg <duración>	Scrapea feeds continuamente cada <duración>; se frena con Ctrl+C
browse [limit]	Muestra los posts recientes de los feeds que seguís (default: 2)
reset	Borra todos los usuarios (y todo lo que les pertenece)

Cuidado con reset: borra la tabla de usuarios, y los feeds, follows y posts se van en cascada con ella. No pide confirmación.

Feeds para probar

• TechCrunch — https://techcrunch.com/feed/
• Hacker News — https://news.ycombinator.com/rss
• Hacker News (newest) — https://hnrss.org/newest
• Wags Lane — https://www.wagslane.dev/index.xml