ghrelease is a simple CLI tool that downloads the latest release assets from Github for MacOS and Linux architectures, specifically "amd64" and "arm64".
The tool automatically identifies your OS and architecture, and downloads the release. If the release is compressed or in an archive format, it will automatically extract and unpack it, no matter how it's compressed, and keep ONLY the binary.
You can also choose to skip the extraction and keep the archive.
brew tap kavishgr/homebrew-tap
brew install --cask ghreleaseDownload the latest binary from the releases section and place it in your $PATH.
A GitHub personal access token is required. The token is validated on startup.
Required Scopes: public_repo (for public repos) or repo (for private repos)
Common Errors:
401 Unauthorized: Invalid or expired token - generate a new one403 Forbidden: Valid token but lacks required permissions - check token scopes- Network errors: Check your internet connection or GitHub API status
Set the token
Method 1: Store in shell config file (Recommended)
Add to ~/.bashrc, ~/.zshrc, or ~/.profile:
echo "export GITHUB_TOKEN='ghp_xxxxxxxxxxxxx'" >> ~/.zshrc
source ~/.zshrcMethod 2: Read from file
Save token to a file:
echo 'ghp_xxxxxxxxxxxxx' > ~/.github-token
chmod 600 ~/.github-tokenAdd to shell config:
echo "export GITHUB_TOKEN=\$(cat ~/.github-token)" >> ~/.zshrc
source ~/.zshrcMethod 3: Set for current session only
Use a space before the command to avoid shell history (works in bash/zsh):
export GITHUB_TOKEN='ghp_xxxxxxxxxxxxx'Verify it's set:
echo $GITHUB_TOKENNote: Avoid typing export GITHUB_TOKEN=... directly in your terminal as it will be saved to shell history.
ghrelease -hAll the supported flags:
-list, -l
Will list all the release/releases found for your OS and Architecture.
Example: cat urls.txt | getghrel -l | sort
Example: echo 'https://github.com/sharkdp/bat' | getghrel -list | sort
Example: echo 'sharkdp/bat' | getghrel -list | sort
-con, -c
Set the concurrency level (default: 2)
Example: cat urls.txt | getghrel -list -con 3 | tee releases.txt
Example: cat releases.txt | getghrel -download -con 3
-download, -d
Download the releases
Default directory in which the release will be downloaded is '/tmp/getghrel'
If the release is compressed or in an archive format, the tool will automatically
extract and unpack it no matter how it's compressed or archived
and keep only the binary.
Example: cat releases.txt | getghrel -download
Example: cat releases.txt | getghrel -download -tempdir '/tmp/test'
-skipextraction, -s
Skip the extraction/unpack process
Example: echo "neovim/neovim" | getghrel -list | getghrel -download -skipextraction
-tempdir, -t
Specify a temporary directory to download/extract the binaries
Example: cat releases.txt | getghrel -download -tempdir '/tmp/test'
-version, -v
Print versionTo list the found releases, create a text file with a complete URL or owner/repo per line, and run:
# List of URLs
# e.g "sharkdp/bat" or https://github.com/sharkdp/bat
cat urls.txt | ghrelease -list -con 3 | tee releases.txt
# Single one
echo "sharkdp/bat" | ghrelease -list | sort
This will display a list of URLs representing the latest release assets found for each repository for your current OS and Architecture.
In rare cases, you may come across additional files like checksums and SBOMs that are specific to your operating system and architecture. I have taken care to exclude them in the regular expression. However, if any such files exist, you can simply filter them out before using the -download flag to ensure a clean download. But don't worry, even if you don't filter the output, the tool will automatically keep only the binaries and remove any unnecessary files. Filtering them out can help save bandwidth.
Note: When you see N/A(not available), it means the repo doesn't have any release assets matching your specific OS and Architecture. For Linux, you might see separate versions for GNU and Musl. You can filter these results using good ole grep.
Duplicates are unlikely, but if they do occur, you can easily filter them out using tools like sort and uniq. That should do the trick.
In case a repository lacks a latest release tag, the tool will search for the most recent release tag instead.
To download the found assets and keep the binaries in a temporary folder (which is /tmp/ghrelease by default), simply use the -download flag:
# List of URLS found with -list
cat releases.txt | ghrelease -download
cat releases.txt | ghrelease -download -con 3
# Single one
echo "https://github.com/sharkdp/bat" | ghrelease -list | getghrel -downloadBefore using -download, remove any lines starting with 'N/A' from the list of found assets.
To download to a different location, use the -tempdir or -t flag :
# List of URLS
cat releases.txt | ghrelease -download -tempdir '/tmp/tempbin'
# Single one
echo "https://github.com/sharkdp/bat" | ghrelease -l | getghrel -d -t '/tmp/tempbin'To keep the archive or compressed release, simply use the -skipextraction option:
echo "helix-editor/helix" | ghrelease -l | getghrel -s -d
echo "neovim/neovim" | ghrelease -l | getghrel -s -dIt is useful for releases that require dependencies bundled together in separate files or folders, rather than just a single binary.
- Fallback Logic: Add a "rescue" regex for releases that only contain the OS but skip the architecture in the filename. Neovim used to do this for macOS (e.g., nvim-macos.tar.gz), they now include both OS and ARCH. yt-dlp is another example.
Why did I create this tool instead of using a package manager?
-
Brew bloat is real: Sometimes you just want a simple tool, but some formula tries to install half of the internet as dependencies. For example, eza (the modern ls) can pull in over 2GB of stuff, which is wild(as of this writing).
-
Some projects don't have the right macOS aarch64 binaries ready to go, or they aren't on package managers at all.
-
If you're on an immutable Linux distro, sometimes you just need a binary right now without firing up a container and installing a bunch of stuff.