gh-celebs/README.md

gh-celebs

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:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Generate a new token (no scopes required for public repo search)
3. 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

1. 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).

2. API Fallback: If local results are insufficient, the tool queries the GitHub Search API for additional repositories.

3. Smart Caching: API results are automatically cached to the local database for future searches.

4. Merging & Sorting: Local and API results are merged, sorted by star count, and the top N results are returned.

5. 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.