awesome/RATE_LIMITS.md

⚡ GitHub Rate Limits - Solved!

The Problem

GitHub API has strict rate limits:

• Without token: 60 requests/hour
• With token: 5000 requests/hour

When indexing awesome lists, you can easily hit the limit!

The Solution

We've implemented a smart rate limit handler that:

1. Gives You Options

When rate limit is hit, you can choose:

• ⏰ Wait and continue (if you have time)
• ⏭️ Skip remaining and continue with what you have
• ❌ Abort the indexing

2. Supports GitHub Tokens

Add your Personal Access Token to get 83x more requests!

Quick Setup (2 minutes):

1. Generate Token

   • Go to: https://github.com/settings/tokens
   • Click "Generate new token (classic)"
   • Give it a name: "awesome-cli"
   • Select scope: public_repo (read-only access to public repos)
   • Click "Generate token"
   • Copy the token (looks like: ghp_xxxxxxxxxxxx)

2. Add to Awesome

   ./awesome settings
   # Choose: Edit settings
   # Paste your token when prompted
   

3. Enjoy 5000 requests/hour! ✨

3. Better UX

• Shows clear wait times in minutes, not seconds
• Helpful tips when rate limit is hit
• Only shows token reminder once per session
• Clean error messages

Usage Tips

For Quick Exploration

# Index just a sample (10 lists)
./awesome index
# Choose: "Index a random sample"

For Full Indexing

# Add your token first
./awesome settings

# Then index everything
./awesome index
# Choose: "Index everything"

If You Hit the Limit

When you see the rate limit message:

Option 1: Skip and Continue (Recommended for first run)

• You'll have partial data to explore
• Can always index more later
• No waiting!

Option 2: Wait

• Best if you're close to finishing
• App will wait automatically
• Can resume where it left off

Option 3: Abort

• Start over later with a token
• Or try a smaller sample first

Rate Limit Math

Without Token (60/hour)

• 1 awesome list = ~1 request (fetch README)
• 1 repository = ~2 requests (repo info + README)
• Average awesome list = ~50 repos = 100 requests
• Result: Can index ~0.5 lists/hour

With Token (5000/hour)

• Result: Can index ~50 lists/hour (100x faster!)

Best Practices

1. Start Small

   ./awesome index → choose "sample"
   

2. Add Token Before Big Index

   ./awesome settings → add token
   ./awesome index → choose "everything"
   

3. Use Skip Option

   • If rate limited, choose "Skip"
   • You'll still have data to explore!
   • Can resume indexing later

4. Index Specific Categories

   ./awesome index → choose "Select specific categories"
   # Pick just what interests you
   

Pro Tips

💡 Token is stored securely in ~/.awesome/awesome.db (SQLite)

💡 Token is displayed masked as ***xxxx in settings

💡 No network transmission - token only used for GitHub API

💡 Read-only access - public_repo scope can't modify anything

💡 Revoke anytime at https://github.com/settings/tokens

Summary

🎯 Problem: Rate limits block indexing ✅ Solution: Smart handler + token support 🚀 Result: 83x more requests, better UX!

---

Stay awesome and never wait for rate limits again! ✨