# Ghfind CLI

> Drive the ghfind CLI to score, scan, roast, and compare GitHub accounts and to browse ghfind.com leaderboards and developer directories from the terminal. Use when the ghfind CLI is installed (or the user wants it installed) and asks to vet, rate, roast, or compare a GitHub user, check if an account is farmed, generate a score badge, or discover developers by language/org/repo. For no-install REST/MCP access to the same engine, prefer the ghfind-score skill.

- Skill: `hikariming/ghfind-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hikariming/ghfind-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hikariming/ghfind-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: AGPL-3.0-or-later
- Author: hikariming (https://skillmd.com/u/hikariming)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hikariming/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

```bash
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:

```bash
ghfind commands --json
ghfind commands show roast --json
```

Score and evidence (factual, deterministic):

```bash
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:

```bash
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:

```bash
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):

```bash
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.