feat: address TODOs and write README.md

2026-08-04 18:00:54 -05:00
parent 79090b3d39
commit ecaa816f1c
4 changed files with 200 additions and 40 deletions
@@ -1,3 +1,77 @@
 # gator

-This is a blog aggregator that was built as part of a [boot.dev](https://boot.dev) course.
+A blog aggregator CLI built as part of the [boot.dev](https://boot.dev) course. Follow RSS feeds and browse their latest posts right from your terminal.
+
+## Requirements
+
+Before you can run gator you'll need to have the following installed:
+
+- **Go** (1.26 or newer)
+- **PostgreSQL** (a running server, local or remote)
+
+## Installation
+
+Install the gator CLI with `go install`:
+
+```sh
+go install github.com/StevanFreeborn/gator@latest
+```
+
+The binary is placed in `$(go env GOPATH)/bin`. Make sure that directory is on your `PATH`:
+
+```sh
+export PATH="$(go env GOPATH)/bin:$PATH"
+```
+
+## Setup
+
+### 1. Create a database
+
+Create a database for gator in your Postgres server:
+
+```sh
+createdb gator
+```
+
+The schema is managed with [goose](https://github.com/pressly/goose) migrations in `sql/schema`. Install goose and apply the migrations:
+
+```sh
+go install github.com/pressly/goose/v3/cmd/goose@latest
+goose -dir sql/schema postgres "postgres://<user>:<password>@localhost:5432/gator?sslmode=disable" up
+```
+
+### 2. Create the config file
+
+gator reads its configuration from `~/.gatorconfig.json`. Create that file with the connection string for your database:
+
+```json
+{
+  "db_url": "postgres://<user>:<password>@localhost:5432/gator?sslmode=disable",
+  "current_user_name": ""
+}
+```
+
+## Usage
+
+Run gator with `gator <command> <args>`. Start by registering a user, then log in:
+
+```sh
+gator register myusername
+gator login myusername
+```
+
+A few commands you can run:
+
+| Command                        | Description                                                                             |
+| ------------------------------ | --------------------------------------------------------------------------------------- |
+| `gator register <name>`        | Register a new user and log in as them                                                  |
+| `gator login <name>`           | Log in as an existing user                                                              |
+| `gator users`                  | List all registered users                                                               |
+| `gator addfeed <name> <url>`   | Add an RSS feed and follow it                                                           |
+| `gator feeds`                  | List all feeds                                                                          |
+| `gator follow <name-or-url>`   | Follow a feed by name or url                                                            |
+| `gator following`              | List the feeds you're following                                                         |
+| `gator unfollow <name-or-url>` | Unfollow a feed by name or url                                                          |
+| `gator browse [limit]`         | Browse posts from your followed feeds                                                   |
+| `gator agg <duration>`         | Continuously fetch posts every `<duration>` (e.g. `60s`); press `q` or `Ctrl-C` to stop |
+| `gator reset`                  | Delete all users and their data                                                         |