ghfind-cli

ghfind CLI

ghfind is a thin client for ghfind.com's deterministic GitHub developer value & trust scoring engine (0-100, no LLM in the scoring core). It performs no local scanning or scoring — every command calls the website API. Do not reimplement scoring locally or import project internals.

Install

npm install -g @hikariming/ghfind   # or: pip install ghfind

Prebuilt binaries: https://github.com/hikariming/ghfind/releases

Configuration

• Default host is https://ghfind.com. Override with GHFIND_HOST or --host (e.g. --host http://localhost:3000 against a local dev server).
• Only the heavy POST /api/scan path (used by scan and roast) requires auth in production: pass GHFIND_API_KEY or --api-key (sent as Authorization: Bearer), or a Turnstile token. Everything else — score, vs, search, exists, stats, leaderboard, developers — is public and unauthenticated.
• Never pass GitHub tokens or LLM API keys to scoring commands; those live on the server. Exceptions: exists --github-token (raises GitHub's anonymous rate limit; the call runs on the caller's quota) and roast --byo-* (runs the roast through the user's own OpenAI-compatible provider).

Commands

Prefer -o json for machine consumption. Discover the full catalog at runtime:

ghfind commands --json
ghfind commands show roast --json

Score and evidence (factual, deterministic):

ghfind score <username> -o json     # preferred first call: public GET /api/score,
                                    # cached, scores never-seen accounts live
ghfind scan <username> -o json      # full evidence: metrics, repos, PRs,
                                    # sub_scores, red_flags (needs api key in prod)

Presentation and comparison:

ghfind roast <username> --lang zh -o markdown   # web-facing roast report
ghfind vs <a> <b> -o json                       # head-to-head; score both first

Utility and discovery:

ghfind exists <username> -o json            # validate handle via GitHub's API
ghfind search <query> -o json               # prefix search over scored accounts
ghfind badge <username> --markdown          # README-ready score badge snippet
ghfind card <username>                      # OG share-card PNG URL
ghfind stats -o json                        # platform totals
ghfind leaderboard --view trending --window 7d -o json
ghfind developers --type language -o json
ghfind developers --type org --value apache -o json
ghfind auth status -o json                  # local credential check, no network

Self-update (only when the user explicitly asks to upgrade; use --dry-run first in automation):

ghfind update check -o json
ghfind update install --method binary --dry-run -o json

Response semantics

• score / scan return factual scoring data: final_score, tier, sub_scores, red_flags, percentile. Use these for automated decisions.
• roast returns the same report a human sees on the website: tags, roast_line, markdown with jokes and sarcasm. Use it only for user-facing copy; never treat roast prose as independent factual evidence.
• vs winner and gap bucket are deterministic; verdict prose is LLM-written and may be null. Both accounts must already be scored (404 need_both otherwise).
• stats / leaderboard / developers are cached discovery surfaces, not fresh per-user facts — before making claims about one account, call score or scan.
• A low score reflects only the account's public GitHub footprint; private-org work is invisible to it.