GitHub Stars CLI

A command-line tool to fetch, cache, and search GitHub stars for any user, with powerful semantic search capabilities.

Features

• Fetch and cache starred repositories for any GitHub user
• Automatically handles pagination to get all stars
• Cache results locally for quick access
• Traditional keyword search across repository fields
• Advanced semantic vector search using embeddings
• Multi-language filtering support
• View detailed information about specific repositories
• GitHub API authentication support to avoid rate limits
• Search across multiple users' starred repositories

Installation

1. Make sure you have Rust and Cargo installed
2. Clone this repository
3. Build and install:

cargo install --path .

Authentication

The tool supports GitHub API authentication to avoid rate limits:

1. Environment Variable: Set the GITHUB_TOKEN environment variable with your GitHub personal access token:

   export GITHUB_TOKEN=your_github_token_here
   

2. Command Line: Provide your token directly via the command line:

   gh-stars fetch <username> --token your_github_token_here
   

The command line option takes precedence over the environment variable.

Creating a GitHub Token

1. Go to your GitHub Settings > Developer settings > Personal access tokens
2. Create a new token with the public_repo scope (or repo for private repositories)
3. Copy the generated token and use it with gh-stars

Usage

Fetch stars for a GitHub user

# First-time fetch
gh-stars fetch <username>

# Force refresh of existing cache
gh-stars fetch <username> --force

# Fetch using a GitHub token
gh-stars fetch <username> --token your_github_token_here

List all starred repositories

# List for specific user(s)
gh-stars list --username=<username>

# List for multiple users
gh-stars list --username=user1,user2,user3

# List all cached users' stars (if no username specified)
gh-stars list

# Limit results
gh-stars list --username=<username> --limit 100

Search repositories

# Basic keyword search for specific user(s)
gh-stars search --username=<username> search query

# Search across multiple users
gh-stars search --username=user1,user2,user3 search query

# Search across all cached users (if no username specified)
gh-stars search search query

# Search with language filtering
gh-stars search --username=<username> --language=rust,go search query

# Limit search results
gh-stars search --username=<username> --limit 100 search query

# Multi-word search terms don't need quotes anymore
gh-stars search chat gpt

View repository details

gh-stars info user/repo

Use the format user/repo such as octocat/Hello-World.

Examples

# Fetch and cache stars for user "octocat"
gh-stars fetch octocat

# Fetch with authentication to avoid rate limits
gh-stars fetch octocat --token your_github_token_here

# List all stars for octocat
gh-stars list --username=octocat

# List stars for multiple users
gh-stars list --username=octocat,rust-lang

# List stars from all cached users
gh-stars list

# Search across all octocat's stars
gh-stars search --username=octocat web framework

# Search across multiple users' stars
gh-stars search --username=octocat,rust-lang web framework

# Search all cached users' stars
gh-stars search web framework

# Search for Rust or Go projects
gh-stars search --username=octocat --language=rust,go

# View details for a specific repository
gh-stars info octocat/Hello-World

Cache Location

Stars are cached in your system's cache directory:

• Linux: ~/.cache/gh-stars/
• macOS: ~/Library/Caches/gh-stars/
• Windows: C:\Users\<username>\AppData\Local\Cache\gh-stars\

How It Works

The tool uses:

• GitHub's REST API to fetch starred repositories
• FastEmbed for generating embeddings of repository metadata
• SQLite with the sqlite-vec extension for vector similarity search
• Rusqlite for database operations
• Clap for command-line argument parsing

Search Types

1. Keyword Search: Performs traditional text matching on repository names, descriptions, and other metadata.
2. Semantic Search: Uses text embeddings to find repositories that are conceptually similar to your query, even if they don't contain the exact keywords.

Troubleshooting

If you encounter issues with vector search:

• Run with --force to regenerate the database if needed

If you encounter GitHub API rate limits:

• Use authentication via the --token flag or GITHUB_TOKEN environment variable
• Wait until the rate limit resets (usually one hour)