hubfetch

Description

A [not very minimal] fetching tool for your GitHub profile. Flex on your friends from terminal itself without even opening a new tab.

This entire script is written purely in python and uses GitHub's REST API for acquiring details of your profile, you can opt out of certain fields and even change the image rendered in accordance to your needs by editing at ~/.config/hubfetch/config.json

The image rendered depends heavily on the terminal as it requires kitty's graphics protocol and full image rendering is supported in those terminals which are capable enough of supporting it.

Don't worry if your favorite terminal doesn't support kitty's graphics protocol as the script downloads chafa as fallback to display your profile picture in ASCII-block art format.

Terminals Supporting Kitty's Graphics Protocol

• Kitty (Native support)
• WezTerm
• Ghostty
• Konsole (KDE's default terminal)

Previews

First Time Installation & Kitty/Non-Kitty Looks

Features

• Comprehensive GitHub Stats: Fetches real-time (ok maybe not that real-time, there is caching of data that is maintained each hour) data including repositories, total stars, forks, followers, and following count.
• Contribution Tracking: Displays your total commits, open issues, and pull requests from the current year using GitHub's GraphQL API.
• Image Rendering:
  • High-Res: Utilizes the Kitty graphics protocol for native, high-resolution avatar rendering.
  • Legacy/Fallback: Automatically detects terminal capabilities and falls back to chafa for high-quality ANSI symbols/block art.
• Caching:
  • Avatar Cache: Refreshes your profile picture every 6 hours.
  • Stats Cache: Keeps your GitHub data fresh with a 1-hour expiration to minimize API calls and maximizes speed.
• Dynamic Customization: Fully configurable via ~/.config/hubfetch/config.json as discussed earlier. Toggle individual fields, adjust image dimensions, or customize the entire color palette with bold and italic Rich styles.
• Secure Authentication: Dedicated auth command to securely handle GitHub Personal Access Tokens (PAT) and verify credentials before setup.
• Modern CLI Experience: Built with Click for a seamless command-line interface and Rich for beautiful, side-by-side terminal layouts.

Dependencies

Chafa (Highly Recommended): Used as the primary fallback for terminals that do not support the Kitty graphics protocol. It converts your GitHub avatar into high-quality ANSI symbols/block art.

While the script does attempt to install in case terminal emulator appears to not support Kitty's graphics protocol, it is highly recommended to install manually in the event that chafa installation fails.

Installation

hubfetch is cross-platform and can be installed via your favorite package manager, as a standalone binary, or directly from source.

Recommended

Since hubfetch is a Python CLI application, installing it via pipx is highly recommended. This ensures it is installed in an isolated environment and made available globally in your PATH.

pipx install hubfetch

Arch/Manjaro (AUR)

yay -S hubfetch
# or
paru -S hubfetch

MacOS & Linux (Homebrew)

brew tap pranavu/tap
brew install hubfetch

Windows (Pre-built Binary/Scoop)

Please refer to releases and download the .exe file you find for hubfetch

Important

It is important to install Chafa separately as it is not bundled with the .exe file

If you prefer to use Scoop:

scoop bucket add PranavU-Coder https://github.com/PranavU-Coder/scoop-bucket.git
scoop install hubfetch

Note

I personally haven't tested these builds for Windows as I am not really a Windows user, if you face any error please raise an issue

Build From Source

git clone https://github.com/PranavU-Coder/hubfetch.git
cd hubfetch

pipx install .
# or
uv tool install . 

Usage

Once installed ensure to authenticate with your PAT:

hubfetch auth

authentication process gives you exact steps to generate your PAT incase you didn't make one yet!

once authenticated just run:

hubfetch

data is cached for an hour so don't expect immediate change in stats after you push an update to your project :p

Tech Stack

Future

Discussed in discussions

All features/bug-fixes being implemented can be visible in the roadmap

A rich issue-template to raise all required changes.

I created a PR for nixpkgs to include in their vast ecosystem but the maintainers turned it down (rightfully, I'm hurt) but I hope someday when this project matures more, it would be accepted in their ecosystem :3

License

MIT

Other