A fast, non-interactive CLI tool for searching GitHub repositories by popularity (stars). Uses a local SQLite database that learns and grows as you search.

Features

Smart Caching: Searches local database first, only hits GitHub API when needed
Popularity-Based: Results sorted by star count (descending)
Dual Output Modes: Clean plain text (default) or JSON (--json)
Repository Updates: Refresh cached repo data with a single command
Rate Limit Awareness: Displays remaining API calls and warns when running low
Configurable: Optional GitHub token for higher rate limits (30 vs 10 calls/minute)
Cross-Platform: Works on Linux, macOS, and Windows

Installation

From Source

git clone https://github.com/yourusername/gh-celebs
cd gh-celebs
cargo build --release

The binary will be available at target/release/gh-celebs.

Prerequisites

Rust 1.70+ (for building from source)
GitHub account (optional, for higher API rate limits)

Usage

Search for Repositories

# Search for "react" (default: top 5 results)
gh-celebs react

# Search with custom limit
gh-celebs react --limit 10
gh-celebs react -n 10

# JSON output for scripting
gh-celebs react --json

# Combine options
gh-celebs machine learning --limit 20 --json

Update Cached Repositories

# Update all cached repositories
gh-celebs update

# Update a specific repository
gh-celebs update facebook/react

Help

gh-celebs --help
gh-celebs update --help

Example Output

Plain Text (Default)

1. facebook/react (220,473 ⭐) - Updated 2026-01-15
   https://github.com/facebook/react
   A declarative, efficient, and flexible JavaScript library for building user interfaces.

2. vuejs/vue (210,123 ⭐) - Updated 2026-01-14
   https://github.com/vuejs/vue
   Vue.js is a progressive, incrementally-adoptable JavaScript framework...

3. vercel/next.js (105,234 ⭐) - Updated 2026-01-16
   https://github.com/vercel/next.js
   The React Framework for the Web

API: [8/10 calls remaining]

JSON Output

{
  "query": "react",
  "limit": 5,
  "api_remaining": 8,
  "api_limit": 10,
  "total_cached": 1247,
  "results": [
    {
      "rank": 1,
      "full_name": "facebook/react",
      "stars": 220473,
      "html_url": "https://github.com/facebook/react",
      "description": "A declarative, efficient, and flexible JavaScript library...",
      "language": "JavaScript",
      "cached_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Configuration

Config File Location

Linux: ~/.config/gh-celebs/config.toml
macOS: ~/Library/Application Support/com.gh-celebs.gh-celebs/config.toml
Windows: %APPDATA%\gh-celebs\gh-celebs\config\config.toml

GitHub Token (Optional)

Add a GitHub personal access token to increase rate limits from 10 to 30 requests per minute:

[github]
token = "ghp_xxxxxxxxxxxxxxxxxxxx"

To create a token:

Go to GitHub → Settings → Developer settings → Personal access tokens
Generate a new token (no scopes required for public repo search)
Add it to your config file

Database Location

The local SQLite database is stored alongside the config:

Linux: ~/.local/share/gh-celebs/repos.db
macOS: ~/Library/Application Support/com.gh-celebs.gh-celebs/repos.db
Windows: %APPDATA%\gh-celebs\gh-celebs\data\repos.db

How It Works

Local Search: When you run a query, the tool first searches the local SQLite database for cached repositories matching your query (by name or description).
API Fallback: If local results are insufficient, the tool queries the GitHub Search API for additional repositories.
Smart Caching: API results are automatically cached to the local database for future searches.
Merging & Sorting: Local and API results are merged, sorted by star count, and the top N results are returned.
Updates: Use the update command to refresh star counts and metadata for cached repositories.

Rate Limits

Anonymous: 10 requests per minute
Authenticated: 30 requests per minute (with token)

The tool displays remaining API calls and warns when running low:

Warning: Rate limit running low (2 remaining)

Tech Stack

Language: Rust
Database: SQLite (via rusqlite)
HTTP Client: reqwest (async)
CLI: clap (derive-based)
Serialization: serde
Error Handling: anyhow

Project Structure

gh-celebs/
├── Cargo.toml
├── README.md
└── src/
    ├── main.rs       # Entry point and orchestration
    ├── cli.rs        # CLI argument definitions
    ├── config.rs     # Configuration loading
    ├── db.rs         # Database operations
    ├── github.rs     # GitHub API client
    ├── models.rs     # Data structures
    ├── output.rs     # Output formatters
    └── search.rs     # Search logic

Exit Codes

0 - Success
1 - Error (invalid arguments, API errors, etc.)

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Future Enhancements

Filter by language (--lang rust)
Sort options (--sort updated, --sort created)
Export to CSV/JSON file (--export results.json)
Fuzzy search matching
Configurable database location

Acknowledgments

Built with ❤️ using Rust and the GitHub API.