ghfind

Search GitHub repos from your terminal. No browser needed.

Install

npm install -g github-search-cli

Or via the curl installer (Linux/macOS — downloads the standalone binary, verifies its SHA256 against the release checksums, no Node needed):

curl -fsSL https://raw.githubusercontent.com/codersdfs/search-cli/main/scripts/install.sh | sh

Or grab a standalone binary (no Node.js needed) from GitHub Releases — ghfind-<os>-<arch> executables for Linux, macOS, and Windows.

Why ghfind?

| | ghfind | gh search (GitHub CLI) | hub | | ------------------------------------------- | -------- | ------------------------ | ----- | | Repo search + qualifiers | ✅ | ✅ | ❌ | | Trending repos (day/week/month/year) | ✅ | ❌ | ❌ | | Full-screen TUI, keyboard-driven | ✅ | ❌ | ❌ | | Bookmarks, tags & release tracking | ✅ | ❌ | ❌ | | Side-by-side repo compare (JSON/CSV/MD) | ✅ | ❌ | ❌ | | Deep-dive (languages, contributors, README) | ✅ | ❌ | ❌ | | Similar repos (shared topics + language) | ✅ | ❌ | ❌ | | Package search, 5 registries | ✅ | ❌ | ❌ | | Org profile | ✅ | ✅ | ❌ | | User profile | ✅ | ❌ | ❌ | | Pipeable JSON / CSV / Markdown export | ✅ | JSON only | ❌ | | No login required | ✅ | ❌ | ❌ |

No separate runtime needed! Only requires Node.js 20+. The TUI needs Bun, which is downloaded automatically at install time. Non-interactive modes work with just Node.js.

| Platform | TUI | CLI modes | | -------------- | ----------------- | --------- | | Node 20+ | ⚠ Bun required | ✅ | | Bun | ✅ | ✅ | | Downloaded Bun | ✅ auto-installed | ✅ |

Use

# TUI
ghfind

# pipe
ghfind "language:Rust stars:>1000" --json | jq '.[].fullName'
ghfind "language:Zig" --count
ghfind --trending --json --since weekly
ghfind login                    # import the gh CLI token or paste one
ghfind org vercel               # org profile: repos, stars, top languages
ghfind user torvalds            # user profile: repos, stars, followers

Non-interactive

ghfind "query" --json        # JSON
ghfind "query" --csv         # CSV
ghfind "query" --markdown    # Markdown
ghfind "query" --count       # count only
ghfind "query" --format urls # one URL per line
ghfind "query" --pipe open   # open in browser
ghfind "query" --pipe clone  # clone commands
ghfind clone facebook/react # clone the repo into ./react (--dir, --ssh)
ghfind release run --tag v9.12.0 --dry-run # dispatch the Release workflow (tag must exist)
ghfind --trending --json     # trending as JSON
ghfind trending rust --json  # trending, filtered by language
ghfind --watch "query"       # poll every 300s
ghfind --releases            # new releases for bookmarked repos
ghfind --compare a/b c/d     # side-by-side comparison
ghfind --compare a/b c/d --json # comparison as JSON|CSV|Markdown
ghfind deep-dive a/b --json  # deep-dive: languages, contributors, README
ghfind similar facebook/react --limit 10  # repos sharing its topics + language
ghfind pkg "query" --json    # npm package search as JSON (default registry)
ghfind pkg clap --registry crates --json          # crates.io
ghfind pkg Newtonsoft --registry nuget --limit 5  # NuGet, --registry npm|crates|rubygems|nuget|maven
ghfind pkg pdf --registry rubygems                # RubyGems
ghfind pkg jackson --registry maven --count       # Maven Central, as a count
# Read-only local state
ghfind bookmarks             # saved repos, newest first
ghfind history --limit 20    # past searches
ghfind saved                 # named searches saved in the TUI
ghfind topics                # popular GitHub topics
ghfind readme a/b            # print a repo README (--raw for no header)
ghfind share a/b --as gh-cli # share snippet (--copy also copies it)
# Agent skills
ghfind skill search testing      # skills installed on this machine
ghfind skill search testing --remote --json  # the skills.sh ecosystem

bookmarks, history, saved, topics, readme and share are read-only: they print what the TUI has stored but never modify local state.

Use with AI agents

ghfind speaks the Model Context Protocol — any MCP client (Claude Code, Cursor, Codex, …) can call its GitHub search as tools:

claude mcp add ghfind -- ghfind mcp

or in your MCP client config:

{
  "mcpServers": {
    "ghfind": { "command": "ghfind", "args": ["mcp"] }
  }
}

Exposed tools: ghfind_search_repos, ghfind_trending, ghfind_package_search (npm, crates.io, RubyGems, NuGet, Maven Central — registry selects it, npm by default), ghfind_npm_packages (the npm-pinned alias), ghfind_org_profile, ghfind_user_profile, ghfind_compare_repos, ghfind_deep_dive, ghfind_similar_repos (repos sharing a repo's topics and language), ghfind_bookmarked_releases, ghfind_skill (a token-efficient CLI usage guide for agents), and ghfind_skill_search (find agent skills, either installed on this machine or in the public skills.sh ecosystem ? read-only, it never installs anything). Unauthenticated requests are rate-limited to 60/hr — set GITHUB_TOKEN in the environment for 5,000/hr.

CLI-first agents can skip MCP entirely:

ghfind skill                      # list agent skills
ghfind skill ghfind-cli           # print the token-efficient CLI guide
ghfind skill search testing       # search installed skills (local scan)
ghfind skill search testing --remote --limit 10 --json  # search skills.sh

ghfind skill search matches skill names first, then descriptions, and reads the SKILL.md files under ~/.codex/skills, ~/.agents/skills, <project>/.codex/skills and <project>/.github/skills (in that priority order, de-duplicated by name). --remote queries the public skills.sh ecosystem instead and returns the npx skills add command for each hit, without installing anything. Set GHFIND_SKILL_ROOTS to override which directories are scanned.

Completions

source <(ghfind --completion bash)
source <(ghfind --completion zsh)
ghfind --completion fish | source

Features

Landing screen (the mode menu shown on launch)

| Key | Action | | --------------------- | ---------------------------- | | ↑ / ↓ — j / k | Navigate mode cards | | Enter | Select mode / open Bookmarks | | b | Jump straight to Bookmarks | | ? or h | Help overlay | | q | Quit ghfind |

Global shortcuts (main view, no overlay active)

| Key | Action | | --------------------- | ---------------------------------------------- | | / | Focus search input | | Enter | Execute search / open selected repo in browser | | ↑ / ↓ — j / k | Navigate results & menus | | Esc | Open / close leader menu (contextual actions) | | Tab | Auto-complete search qualifier | | Ctrl+E | Export results (JSON / CSV / Markdown / text) | | ? or Ctrl+H | Help overlay | | 1–5 | Switch trending tabs (Today → All) | | ← / → — h / l | Switch trending tabs (left/right) | | PageUp | Jump to top of results | | PageDown | Load next page of results | | q | Quit ghfind |

Mouse — every list is clickable, and the keyboard and mouse are interchangeable

| Input | Action | | --------------------------------------- | ----------------------------------------- | | Click | Select a row / card / trending tab | | Double-click | Open the repo, or run the action | | Scroll wheel | Move the selection, or scroll a long pane | | Click outside an overlay | Dismiss it (same as Esc) | | Click the query box | Focus the search input | | Click ☰ menu (bottom-right) | Open the leader menu |

Error recovery — active only while the matching error is in the status bar

| Key | Action | | --- | --------------------------------------------- | | r | Retry the failed search / trending load | | t | Fix the GitHub token (401 bad token, 403 SSO) | | u | Search without a token (401) | | c | Change token (rate limit) |

Leader menu — press Esc (or click ☰ menu), navigate with ↑/↓, press Enter to dispatch

Actions shown depend on current mode (search vs trending) and selection:

| Menu item | Description | | --------------- | ------------------------------------------------------- | | Sort | Cycle sort strategy (best-match, stars, updated, forks) | | Limit | Cycle result limit (10, 25, 50, 100) | | Refresh | Re-run current search (or reload trending) | | Toggle trending | Switch between search and trending views | | Deep-dive | Show languages, contributors, README excerpt | | Readme | Full markdown README viewer (inline images included) | | Activity graph | Toggle commit chart fullscreen | | Bookmark | Save / unsave selected repo | | Compare | Add/remove repo to comparison set | | Compare view | Show side-by-side comparison table | | Open in browser | Open selected repo URL | | Clone | Clone the repo to disk (into the cwd) | | History | Recall past searches | | Saved searches | Load a saved search | | Save search | Save current query | | Export | Export results to JSON / CSV / Markdown | | Share repo | Copy repo link to clipboard | | Org profile | Org summary — repos, total stars, top languages | | Notifications | View and dismiss alerts | | Topics | Browse popular GitHub topics | | Bookmarks panel | Browse saved bookmarks | | Help | Keybindings reference |

Overlay-specific shortcuts

| Key | Context | Action | | -------------------------------- | ---------------------------------------------------- | ------------------------------------------- | | Esc / q | Any overlay | Close overlay | | Enter | Leader / History / Saved / Export / Topics / Share | Confirm selection | | d | History / Bookmarks / Saved searches / Notifications | Delete current entry | | Ctrl+X | History | Clear all history | | Ctrl+C | Notifications | Dismiss all notifications | | i | README viewer | Toggle inline images on/off | | Y / N / L | Update modal | Yes (install) / No (skip) / Later (dismiss) | | ↑ / ↓ — j / k | Update modal | Scroll release notes | | PgUp / PgDn / Home / End | Update modal | Jump through release notes |

Trending tabs: 1–5 (Today → All) or ←/→ — h/l

Most actions are accessed via the leader menu (Esc, or the ☰ menu button in the bottom-right corner). This keeps the keymap minimal while providing a full command palette. The leader menu filters actions contextually — items that don't apply (e.g., Bookmark with no repo selected) are hidden.

Search syntax

language:Rust stars:>1000 topic:cli
"machine learning" language:Python stars:>5000
topic:cli -language:JavaScript
org:rust-lang language:Rust

Prefix with - to exclude. Supported: language, stars, forks, topics, followers, size, fork, archived, topic, user, org, repo, updated, pushed, visibility, license, created, in.

Queries are parsed and checked before the request is sent:

• Qualifier typos are corrected — langauge:Rust → language:Rust, star:1000 → stars:1000. Correction is limited to the qualifiers listed above, so is:, has: and props.* pass through untouched.
• Counts accept k/m — stars:10k means 10,000 or more. A bare count keeps GitHub's exact-match meaning, so use stars:>=100 or stars:10k rather than stars:100.
• An invalid value is rejected with the fix, not sent to GitHub: ⚠ Invalid query: "stars:abc" is not a number — use stars:100, stars:>=100, or stars:1k..10k
• An empty result suggests how to loosen the query — qualifiers are ranked by how sharply they narrow results, and the message offers a concrete retry.

See docs/HOW-TO.md for a task-oriented walkthrough.

Config

~/.config/ghfind/config.json (auto-created, or run ghfind init; ghfind login will set your GitHub token):

{
  "defaultSort": "stars",
  "defaultLimit": 50,
  "theme": "tokyo-night",
  "githubToken": "ghp_..."
}

githubTokens: ["ghp_one", "ghp_two"] additionally enables round-robin rotation across multiple tokens when you hit rate limits. The env var GITHUB_TOKEN takes precedence over the file.

Env: GITHUB_TOKEN, GHFIND_CONFIG, GHFIND_LOG (path — write TUI diagnostics there; unset by default), GHFIND_SKILL_ROOTS (path-separator separated skill directories for ghfind skill search), XDG_CONFIG_HOME, XDG_STATE_HOME, NO_COLOR (disables colored --doctor output, per no-color.org)

From source

git clone https://github.com/codersdfs/search-cli.git
cd ghfind

# With Bun (recommended for TUI)
bun install
bun start        # TUI
bun test         # 895 tests
bun run check    # format check + tests — the green gate
bun run build    # build dist/

# Or with npm
npm install
npm start        # TUI (requires Node 20+)
npm test         # 895 tests
npm run build    # build dist/

> Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for commands,
> conventions, and the two tracked quality gates (`typecheck`, `lint`).

Known limitations

README image rendering has one deliberate blind spot and one hard one:

• Images smaller than 100 px on any edge are skipped. For <img> tags the declared width/height is trusted, so an image that understates its size is hidden (a README that overstates nothing is never affected). Markdown ![]() images declare no size, so they are measured from the image header instead — still before any pixels are decoded.
• SVG is not rendered — the rasteriser cannot draw it, so SVGs (and badge-service images, which are tiny SVGs with text baked in) show an 🖼 alt caption instead.

An image wrapped in a link — [![alt](shot.png)](url), the badge-and-screenshot style — renders fine and keeps its link: the image cells carry an OSC 8 hyperlink, so clicking it opens the target in your browser. See .issues/tickets/readme-image-rendering.md for the architecture, measurements, and remaining work.

Changelog

Recent releases (full history in CHANGELOG.md):

v9.13.0

• ghfind similar <owner/repo> finds repos like one you already know — topics first, then primary language, merged and de-duplicated across widening queries; forks, archived repos and the source repo itself are excluded, and a star floor scales with the source's popularity
• MCP ghfind_similar_repos gives agents the same discovery — rendered list plus a structured { repo, count, repos, queries } payload showing which searches produced the answer

v9.12.1

• One-shot CLI search honors ghfind login's saved token — every surface now resolves flag > state > config (env wins over the file), and the config file's githubTokens rotation list actually works; previously only the env var was read, silently capping at 60/hr
• GitHub 403s carry GitHub's own reason — one seam classifies 401/403/rate-limit/forbidden with the reset time and GitHub's message, replacing nine drifted header builders and raw error 403 dumps
• ghfind pkg totals admit when unknown — npm, crates.io, NuGet and Maven Central print a bound (30+) like RubyGems instead of passing off the page length as an exact count

v9.12.0

• ghfind pkg searches five package registries — --registry npm|crates|rubygems|nuget|maven selects one (npm default), every download figure is labelled with the window its registry actually publishes (/mo, /90d, total, n/a), and an unparseable 200 is an error instead of zero results
• ghfind release run --tag <v> dispatches the Release workflow — the CLI equivalent of gh workflow run release --ref <v>, with --dry-run to rehearse
• --registry now belongs to ghfind pkg alone — elsewhere it is rejected instead of silently ignored, and --sort is validated against the chosen registry on every path including the browser

License

MIT