list-github-stars

Tiny CLI program capable of retrieving a GitHub user's starred repositories and formatting the data into a nice Markdown document. You can see an example of the program's output here.

Usage

Authentication is made via personal access tokens. Create a token, export it to the environment variable GITHUB_TOKEN, and run. Output is written to STDOUT:

./bin/lgs > my-stars.md

Flags:

• --token, -t — GitHub PAT (defaults to $GITHUB_TOKEN).
• --user, -u — list a different user's stars (defaults to the authenticated user).
• --version, -v — print version, commit, and build timestamp.

You can use external programs such as pandoc to convert the output to other formats:

# MS Word document
./bin/lgs | pandoc -o stars.docx

# HTML page
./bin/lgs | pandoc -o stars.html

# HTML page with custom stylesheet
./bin/lgs | pandoc -o stars.html --self-contained --css=style.css

Run with Docker

Images are published to GitHub Container Registry:

docker run --rm \
    -e GITHUB_TOKEN="your-github-auth-token" \
    ghcr.io/caian-org/list-github-stars:latest > my-stars.md

Build from source

This repo uses devbox + just. Inside devbox shell:

just build lgs              # produces ./bin/lgs
./bin/lgs --version

Common targets:

just test                   # go test ./...
just test-race              # go test ./... -race
just lint                   # go vet ./...
just release-check          # goreleaser check
just release-snapshot       # local goreleaser dry-run into dist/

Releases

Releases are tag-driven. Pushing a v* tag runs .github/workflows/release.yml, which uses GoReleaser to publish:

• Multi-platform archives (linux/darwin/windows × amd64/arm64) attached to a GitHub Release.
• A Docker image to ghcr.io/caian-org/list-github-stars:<tag> and :latest.

A daily-run workflow rewrites a public gist with fresh output every day at 03:00 UTC, consuming the :latest image.

License

To the extent possible under law, Caian Ertl has waived all copyright and related or neighboring rights to this work. In the spirit of freedom of information, I encourage you to fork, modify, change, share, or do whatever you like with this project! ^C ^V