ghfz

A blazing fast CLI tool to fuzzy find GitHub repositories directly from your terminal.

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
  • Fuzzy Search
  • Commands
• Configuration
• Rate Limiting
• Data Storage
• Development
• Packaging
• Changelog
• Acknowledgements
• Support

Features

• 🔍 Fuzzy find GitHub users, repositories, and pull requests.
• ➕ Add a user's repositories to your local database.
• 🗑️ Remove user repositories from your database.
• 🔄 Sync your local database with GitHub API.
• 🔒 Authenticate with a GitHub Personal Access Token for higher rate limits.
• 🌐 Open selected repositories directly in your default browser.

Prerequisites

ghfz relies on fzf for fuzzy searching. Please ensure fzf is installed before using ghfz:

• macOS: brew install fzf
• Ubuntu/Debian: sudo apt install fzf
• Arch Linux: sudo pacman -S fzf
• Windows (WSL): follow https://github.com/junegunn/fzf#installation

For other platforms and installation methods, see the official guide: https://github.com/junegunn/fzf#installation

Installation

Install via npm:

npm install -g ghfz@latest

Or use the latest unpublished version:

bash -c "$(curl -fsSL https://ghfz.netlify.app/run.sh)" -- https://ghfz.netlify.app/ghfz.tgz

Usage

Once installed, run:

ghfz [command]

Fuzzy Search

Running without arguments launches the interactive fuzzy search:

ghfz

You can search across:

• GitHub user homepages
• User repositories pages
• Individual repository pages
• Pull request pages

Type to filter and press Enter to open your selection in the browser.

Commands

• add

  Add all public repositories of a GitHub user to the local database:

ghfz add

Prompts for a username and fetches repos via GitHub API.

• remove

  Remove one or more users and their repos from the database:

ghfz remove

Prompts to select users in a multi-select interface.

• sync

  Sync local database with GitHub for updated repositories:

ghfz sync

By default, syncs only selected users' data. To sync all:

ghfz sync --all

• auth

  Store your GitHub Personal Access Token for increased rate limits:

ghfz auth

Prompts to enter your PAT, securely saved in your config directory.

Use ghfz --help to view all available commands and options.

Configuration

Your GitHub PAT is stored at:

# Linux
~/.config/ghfz-nodejs/github_pat.txt

Rate Limiting

GitHub API limits unauthenticated requests to 60 per hour. When you encounter HTTP 403 errors due to rate limits, authenticate with a GitHub Personal Access Token (PAT) to increase your limit to 5,000 requests per hour.

1. Generate a PAT:
   • Visit https://github.com/settings/tokens
   • Click Generate new token (classic), provide a name, select the repo scope (or others as needed), and generate your token.
   • Copy the generated token.
2. Authenticate with ghfz:

ghfz auth

When prompted, paste your PAT. The token is stored securely and used for subsequent API requests.

For more details, see GitHub's documentation: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Data Storage

User and repository data are stored under your system data directory, for example:

# Linux
~/.local/share/ghfz-nodejs/users.json
~/.local/share/ghfz-nodejs/repos.json

Mock data is seeded on first run from the MockData folder.

Development

Clone the repository and install dependencies:

git clone https://github.com/dhruvdhaduk-simform/ghfz.git
cd ghfz
npm install

Build the project:

npm run build

OR Run in development/watch mode:

npm run dev

Then, to start the CLI :

npm start

Format code with Prettier:

npm run format

Packaging

• npm run pack — Clean, build, and generate a packaged .tgz and run.sh in the dist/ folder.

Changelog

See the Releases for detailed changelog and version history.

Acknowledgements

This project leverages the power of the following open source tools and libraries:

• TypeScript — for static typing and modern JavaScript features
• Node.js — as the runtime environment
• fzf — for blazing fast fuzzy search in the terminal
• yargs — for command-line interface parsing
• prompts — for interactive user prompts
• env-paths — for managing config and data directories
• zod — for runtime schema validation
• open — for cross-platform URL opening

Support

For questions or feedback, please open an issue or contact [email protected].