BinHarbor is a personal Python project designed to reduce the effort required to maintain and update locally installed Linux binaries.
The project scans local directories for downloaded binaries, detects installed versions, and stores this information for further processing. Current versions can be stored in JSON format, with support for SQLite planned for future releases.
BinHarbor checks upstream software sources such as GitHub Releases, vendor download pages, and other supported providers to identify available updates. It then compares installed versions with the latest available releases.
When an update is available, BinHarbor can automatically download the new release, extract archives if required, replace the existing binary, and apply the appropriate file permissions.
- Discover locally installed binaries
- Detect installed software versions
- Check for updates from supported providers
- Download and install new releases
- Manage binary updates from a single location
- Linux AMD64 support
- Linux ARM64 support
- GitHub Releases support
- HashiCorp Releases support
- Helm Releases support
- Automatic binary updates
- XDG-compliant configuration
- Automatic binary backups
- GitHub Actions build pipeline
BinHarbor is primarily a learning project focused on Python development, automation, and Linux system administration while providing a practical solution for managing standalone binaries.
BinHarbor currently supports binaries installed in user-writable directories such as:
- ~/bin
- ~/.bin
- ~/.local/bin
Binaries installed in system directories such as /usr/local/bin, /usr/bin, or other locations that require elevated privileges can be detected, but automatic updates are currently not supported.
In these cases, BinHarbor downloads and extracts the updated binary, but installation must be completed manually using sudo or another privileged account.
Support for automatic updates in privileged system directories may be added in a future release.
BinHarbor can access GitHub releases anonymously without any configuration.
- For Anonymous Access no GitHub token required.
GitHub allows approximately 60 API requests per hour for anonymous users. This is sufficient for most personal setups and occasional update checks.
To increase the GitHub API rate limit, configure a Personal Access Token:
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
Authenticated requests receive a significantly higher rate limit:
| Mode | Requests per Hour |
|---|---|
| Anonymous | 60 |
| Authenticated | 5000 |
BinHarbor automatically uses the token when the GITHUB_TOKEN environment variable is present.
## Install BinHarbor
wget -O ~/bin/binharbor https://github.com/hth73/hth-binharbor/releases/download/v1.0.1/binharbor-linux-amd64
chmod +x ~/bin/binharbor## Show Help
binharbor --help
usage: binharbor [-h] [-c] [-d] [-i] [-l] [-v]
BinHarbor - Manage and update local Linux binaries
options:
-h, --help show this help message and exit
-c, --config Open configuration file
-d, --debug Enable debug output
-i, --init Create default configuration
-l, --list Lists all installed binaries
-v, --version show program's version number and exit
https://github.com/hth73/hth-binharbor## Create your first default Configuration
binharbor --init
Backup created: ${HOME}/.config/binharbor/binharbor.yaml.bak
Created: ${HOME}/.config/binharbor/binharbor.yaml
## Edit the configuration with your default editor
## --config switch use 'export EDITOR="vim"'
binharbor --config
# or
nano ${HOME}/.config/binharbor/binharbor.yaml
# ---
search_paths:
- ~/bin
- ~/.bin
- ~/.local/bin
- /usr/local/bin
binaries:
terraform:
version_command:
- terraform
- version
release_type: hashicorp
github_repo: hashicorp/terraform
terragrunt:
version_command:
- terragrunt
- --version
release_type: github
github_repo: gruntwork-io/terragrunt
# ... When BinHarbor detects a newer version of a configured binary, it performs the following steps:
- A temporary cache download directory is created under:
$HOME/.cache/binharbor/downloads - The appropriate release asset is downloaded from GitHub, HashiCorp, Helm, or another configured source.
- The archive is extracted in the cache directory.
Before installing the new version, BinHarbor creates a backup of the existing binary:
<binary>.bak- The new binary is copied to the configured installation directory (for example ~/bin).
BinHarbor updates its local database: $HOME/.local/share/binharbor/binaries.json
- This file stores metadata such as the installed version, latest available version, download URL, and update status.
- Temporary download and extraction files are removed from the cache directory.
As a result, only the installed binary, its backup, and the metadata file remain on the system.
## First query and output
binharbor
# ...
Checking terraform...
Downloading: https://releases.hashicorp.com/terraform/1.15.5/terraform_1.15.5_linux_amd64.zip
Checking terragrunt...
Checking spf...
Checking kubectl...
# ...
Checking packer...
Downloading: https://releases.hashicorp.com/packer/1.15.3/packer_1.15.3_linux_amd64.zip
=== Updates Available ===
terraform 1.14.8 -> 1.15.5
packer 1.15.1 -> 1.15.4
=== Up To Date ===
spf 1.5.0
kubectl 1.36.1
# ...## List all managed binaries
binharbor --list
Installed Binaries
terraform 1.15.5
spf 1.5.0
kubectl 1.36.1
# ...
packer 1.15.4
Total: 15## Debug output
binharbor --debug
[DEBUG] Loading config: /home/$USER/.config/binharbor/binharbor.yaml
[DEBUG] Loaded 15 binaries
[DEBUG] Detected architecture: x86_64
[DEBUG] System info: {'os': 'linux', 'architecture': 'amd64'}
[DEBUG] Scanning: /home/$USER/bin
...
[DEBUG] Found binary: terraform
[DEBUG] Path: /home/$USER/bin/terraform
...
[DEBUG] Scanning: /home/$USER/.bin
[DEBUG] Directory does not exist: /home/$USER/.bin
[DEBUG] Scanning: /home/$USER/.local/bin
[DEBUG] Scanning: /usr/local/bin
...
[DEBUG] Detected 15 binaries
Checking terraform...
[DEBUG] Running command: /home/$USER/bin/terraform version
[DEBUG] Local version: 1.14.8
[DEBUG] Latest GitHub release: 1.15.5
[DEBUG] Download URL: https://releases.hashicorp.com/terraform/1.15.5/terraform_1.15.5_linux_amd64.zip
Downloading: https://releases.hashicorp.com/terraform/1.15.5/terraform_1.15.5_linux_amd64.zip
[DEBUG] Destination: /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64.zip
[DEBUG] HTTP Status: 200
[DEBUG] Download completed: /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64.zip
[DEBUG] Extracting archive: /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64.zip
[DEBUG] Extracted 2 files to /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64
[DEBUG] Binary path: /home/$USER/bin/terraform
[DEBUG] Installing binary: terraform
[DEBUG] Source: /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64/terraform
[DEBUG] Target: /home/$USER/bin/terraform
[DEBUG] Backup created: /home/$USER/bin/terraform.bak
[DEBUG] Installed: /home/$USER/bin/terraform
[DEBUG] Permissions set: 755
[DEBUG] Installed return value: True
[DEBUG] Removing: /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64.zip
[DEBUG] Removing: /home/$USER/.cache/binharbor/downloads/terraform_1.15.5_linux_amd64If binaries are located in /usr/local/bin or other directories where the current user does not have write permissions, updates cannot be installed automatically.
In this case, BinHarbor downloads and extracts the updated binary, but the installation step is skipped. The downloaded files remain available in the cache directory /home/$USER/.cache/binharbor/downloads and must be installed manually using sudo or another privileged account.
# Example Output:
[DEBUG] Source: /home/$USER/.cache/binharbor/downloads/eza_x86_64-unknown-linux-gnu/eza
[DEBUG] Target: /usr/local/bin/eza
Skipped: no write permission for /usr/local/bin
=== Updates Available ===
eza 0.23.3 -> 0.23.4© 2026 Helmut Thurnhofer - License: MIT