feat(github): improve rate limit messages with auth detection

- Add get_gh_cli_token() to use gh CLI if authenticated
- Update get_github_rate_limit() to:
  - Try GITHUB_TOKEN env var first
  - Fall back to gh CLI token
  - Return authenticated and token_source fields
- Add get_github_rate_limit_help() with:
  - Deep link to create PAT with pre-selected scopes
  - gh auth login instructions
  - Environment variable setup guide
- Update audit.py to:
  - Show auth source: "(via gh CLI)" or "(via GITHUB_TOKEN)"
  - Display help when unauthenticated with 60/60 limit

Author: CybotTM

audit.py

@@ -28,7 +28,7 @@
 from cli_audit.detection import audit_tool_installation  # noqa: E402
 from cli_audit.snapshot import load_snapshot, write_snapshot, render_from_snapshot, get_snapshot_path  # noqa: E402
 from cli_audit.render import render_table, print_summary, status_icon  # noqa: E402
-from cli_audit.collectors import get_github_rate_limit  # noqa: E402
+from cli_audit.collectors import get_github_rate_limit, get_github_rate_limit_help  # noqa: E402
 from cli_audit import collectors  # noqa: E402
 from cli_audit.logging_config import setup_logging  # noqa: E402
 # Split file support (Phase 2.1)
@@ -353,10 +353,27 @@ def cmd_update(args: argparse.Namespace) -> int:
     if rate_limit:
         remaining = rate_limit.get("remaining", 0)
         limit = rate_limit.get("limit", 0)
+        authenticated = rate_limit.get("authenticated", False)
+        token_source = rate_limit.get("token_source", "")
+
+        # Build status message
+        auth_info = ""
+        if authenticated:
+            if token_source == "gh_cli":
+                auth_info = " (via gh CLI)"
+            elif token_source == "GITHUB_TOKEN":
+                auth_info = " (via GITHUB_TOKEN)"
+
         if remaining < limit * 0.2:  # Warn if less than 20% remaining
-            print(f"⚠️  GitHub rate limit: {remaining}/{limit} remaining", file=sys.stderr)
+            print(f"⚠️  GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr)
+            if not authenticated:
+                print(get_github_rate_limit_help(), file=sys.stderr)
+        elif not authenticated and limit == 60:
+            # Unauthenticated with default limit - suggest authentication
+            print(f"ℹ️  GitHub rate limit: {remaining}/{limit} remaining (unauthenticated)", file=sys.stderr)
+            print(get_github_rate_limit_help(), file=sys.stderr)
         else:
-            print(f"✓ GitHub rate limit: {remaining}/{limit} remaining", file=sys.stderr)
+            print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr)
 
     print(f"# Collecting fresh data for {total} tools...", file=sys.stderr)
     est_time = int((total / MAX_WORKERS) * 3 * 1.5)
@@ -487,10 +504,20 @@ def cmd_update(args: argparse.Namespace) -> int:
         if rate_limit:
             remaining = rate_limit.get("remaining", 0)
             limit = rate_limit.get("limit", 0)
-            if remaining < limit * 0.2:  # Warn if less than 20% remaining
-                print(f"⚠️  GitHub rate limit: {remaining}/{limit} remaining", file=sys.stderr)
+            authenticated = rate_limit.get("authenticated", False)
+            token_source = rate_limit.get("token_source", "")
+
+            auth_info = ""
+            if authenticated:
+                if token_source == "gh_cli":
+                    auth_info = " (via gh CLI)"
+                elif token_source == "GITHUB_TOKEN":
+                    auth_info = " (via GITHUB_TOKEN)"
+
+            if remaining < limit * 0.2:
+                print(f"⚠️  GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr)
             else:
-                print(f"✓ GitHub rate limit: {remaining}/{limit} remaining", file=sys.stderr)
+                print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr)
 
         # Suggest package manager upgrades
         from cli_audit.catalog import suggest_package_manager_upgrades
@@ -626,7 +653,21 @@ def cmd_update_baseline(args: argparse.Namespace) -> int:
     if rate_limit:
         remaining = rate_limit.get("remaining", 0)
         limit = rate_limit.get("limit", 0)
-        print(f"✓ GitHub rate limit: {remaining}/{limit} remaining", file=sys.stderr)
+        authenticated = rate_limit.get("authenticated", False)
+        token_source = rate_limit.get("token_source", "")
+
+        auth_info = ""
+        if authenticated:
+            if token_source == "gh_cli":
+                auth_info = " (via gh CLI)"
+            elif token_source == "GITHUB_TOKEN":
+                auth_info = " (via GITHUB_TOKEN)"
+
+        if not authenticated and limit == 60:
+            print(f"ℹ️  GitHub rate limit: {remaining}/{limit} remaining (unauthenticated)", file=sys.stderr)
+            print(get_github_rate_limit_help(), file=sys.stderr)
+        else:
+            print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr)
 
     print(f"# Collecting upstream versions for {total} tools...", file=sys.stderr)
 
@@ -671,7 +712,17 @@ def cmd_update_baseline(args: argparse.Namespace) -> int:
     if rate_limit:
         remaining = rate_limit.get("remaining", 0)
         limit = rate_limit.get("limit", 0)
-        print(f"✓ GitHub rate limit: {remaining}/{limit} remaining", file=sys.stderr)
+        authenticated = rate_limit.get("authenticated", False)
+        token_source = rate_limit.get("token_source", "")
+
+        auth_info = ""
+        if authenticated:
+            if token_source == "gh_cli":
+                auth_info = " (via gh CLI)"
+            elif token_source == "GITHUB_TOKEN":
+                auth_info = " (via GITHUB_TOKEN)"
+
+        print(f"✓ GitHub rate limit: {remaining}/{limit} remaining{auth_info}", file=sys.stderr)
 
     return 0
 

cli_audit/collectors.py

@@ -374,6 +374,44 @@ def version_key(v: str) -> tuple:
     return "", ""
 
 
+def get_gh_cli_token() -> str | None:
+    """Try to get GitHub token from gh CLI if authenticated.
+
+    Returns:
+        Token string or None if gh CLI is not available/authenticated
+    """
+    import shutil
+    import subprocess
+
+    if not shutil.which("gh"):
+        return None
+
+    try:
+        # Check if gh is authenticated
+        result = subprocess.run(
+            ["gh", "auth", "status"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+
+        # Get the token
+        result = subprocess.run(
+            ["gh", "auth", "token"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except Exception:
+        pass
+
+    return None
+
+
 def get_github_rate_limit() -> dict[str, Any]:
     """Get GitHub API rate limit status.
 
@@ -384,7 +422,17 @@ def get_github_rate_limit() -> dict[str, Any]:
 
     try:
         headers = {"User-Agent": "ai-cli-preparation/2.0"}
+
+        # Try to get token from multiple sources
         token = os.environ.get("GITHUB_TOKEN")
+        token_source = "GITHUB_TOKEN" if token else None
+
+        # Try gh CLI if no token in environment
+        if not token:
+            token = get_gh_cli_token()
+            if token:
+                token_source = "gh_cli"
+
         if token:
             headers["Authorization"] = f"token {token}"
 
@@ -396,7 +444,48 @@ def get_github_rate_limit() -> dict[str, Any]:
             "remaining": core.get("remaining", 0),
             "used": core.get("used", 0),
             "reset": core.get("reset", 0),
+            "authenticated": token is not None,
+            "token_source": token_source,
         }
     except Exception as e:
         logger.debug(f"Failed to get GitHub rate limit: {e}")
         return {}
+
+
+def get_github_rate_limit_help() -> str:
+    """Get helpful instructions for setting up GitHub authentication.
+
+    Returns:
+        Multiline string with instructions
+    """
+    import shutil
+
+    lines = []
+
+    # Check if gh CLI is available
+    has_gh = shutil.which("gh") is not None
+
+    lines.append("")
+    lines.append("To increase GitHub API rate limit from 60 to 5,000 requests/hour:")
+    lines.append("")
+
+    if has_gh:
+        lines.append("Option 1 (Recommended): Use GitHub CLI (already installed)")
+        lines.append("  gh auth login")
+        lines.append("")
+        lines.append("Option 2: Set GITHUB_TOKEN environment variable")
+    else:
+        lines.append("Option 1 (Recommended): Install and authenticate GitHub CLI")
+        lines.append("  # Install: https://cli.github.com/")
+        lines.append("  gh auth login")
+        lines.append("")
+        lines.append("Option 2: Set GITHUB_TOKEN environment variable")
+
+    # Deep link to create PAT with minimal required scopes
+    # The 'public_repo' scope is needed for accessing public repository data
+    pat_url = "https://github.com/settings/tokens/new?description=CLI%20Toolset&scopes=public_repo"
+    lines.append(f"  1. Create a PAT: {pat_url}")
+    lines.append("  2. Add to your shell profile:")
+    lines.append("     export GITHUB_TOKEN='ghp_your_token_here'")
+
+    return "\n".join(lines)