bin - Effortless Binary Manager

A lightweight, cross-platform binary manager that simplifies downloading, installing, and managing binaries without requiring root privileges.

🚀 Why bin?

Modern development tools are increasingly distributed as single binary releases thanks to languages like Go, Rust, and Deno. While this makes distribution easier, it creates challenges for updates and tracking.

bin solves these problems by:

• Zero Configuration: Works out of the box without complex setup, scoring & filtering found the right package
• No Root Required: Install binaries to user directories without sudo
• Version Management: Track, update, and rollback binary versions
• Lightweight: Minimal overhead compared to manually download and install releases
• Multiple Sources:
  • GitHub Releases
  • Gitlab Releases
  • Codeberg Releases
  • Docker Images
  • HTTP Releases (Hashicorp, Helm)
  • Go Install

For a comprehensive list, see the Tools Wiki.

📦 Installation

Quick Install

1. Download bin from the releases
2. Run ./bin install github.com/marcosnils/bin so bin is managed by bin itself
3. Run bin ls to make sure bin has been installed correctly. You can now remove the first file you downloaded.
4. Enjoy!

Quick install from Scoop (Windows)

Run these commands to install bin from scoop.

scoop bucket add extras
scoop install extras/bin

📚 Commands Reference

Tips: if bin is unable to found the right package, try bin install -a to show all possible download options (skip scoring & filtering).

🎯 Supported providers

GitHub Releases

Github provider will use Github API to found releases matching your workstation specs.

At the moment, bin does only consider the latest release from Github according to the following definition:

The latest release is the most recent non-prerelease, non-draft release, sorted by the created_at attribute. The created_at attribute is the date of the commit used for the release, and not the date when the release was drafted or published.

You can however install a specific pre-release by specifying the URL for the pre-release, e.g. bin install https://github.com/bufbuild/buf/releases/tag/v0.40.0.

Configuration

Usage

# installs latest Kind release
bin install github.com/kubernetes-sigs/kind

# installs a specific release
bin install github.com/kubernetes-sigs/kind/releases/tag/v0.8.0

# installs latest on a specific path
bin install github.com/kubernetes-sigs/kind ~/bin/kind

# installs latest on a specific path and show all possible download options (skip scoring & filtering)
bin install -a github.com/yt-dlp/yt-dlp

or explicit

bin install --provider github github.companyname.com/custom/repo

Gitlab Releases

Gitlab provider will use Gitlab API to found releases matching your workstation specs

Configuration

Usage

bin install gitlab.com/gitlab-org/cli

or explicit

bin install --provider gitlab gitlab.companyname.com/custom/repo

Codeberg Releases

Codeberg provider uses the Gitea/Forgejo API (GitHub-compatible) to find releases matching your workstation specs. Codeberg is a free and open-source alternative to GitHub, hosted at codeberg.org.

Configuration

Usage

# installs latest mergiraf release
bin install codeberg.org/mergiraf/mergiraf

# installs a specific release
bin install codeberg.org/mergiraf/mergiraf/releases/tag/v1.0.0

# installs latest on a specific path
bin install codeberg.org/mergiraf/mergiraf ~/bin/mergiraf

or explicit

bin install --provider codeberg codeberg.org/custom/repo

Docker Images

Docker is also supported or any Docker client compatible runtime.

Configuration

Any variable supported by Docker, see https://docs.docker.com/reference/cli/docker/

Usage

# install the `light` tag for terraform
bin install docker://hashicorp/terraform:light

# install the latest version of calico/node
bin install docker://quay.io/calico/node

For other runtime (like Podman) or for remote docker engine, simply export DOCKER_HOST envvar:

export DOCKER_HOST="unix:///path/to/unix/socket"
bin install docker://quay.io/calico/node

HTTP Releases

Configuration

None.

Usage

Some projects distribute their binaries from a plain HTTP download page instead of GitHub-style release assets. bin supports these through dedicated HTTP providers, selected automatically by host:

• releases.hashicorp.com (Terraform, Vault, ...)
• get.helm.sh (Helm)

bin install releases.hashicorp.com/terraform
bin install get.helm.sh

To install a specific version, use the versioned URL (the binary matching your platform is selected automatically):

bin install https://releases.hashicorp.com/terraform/1.5.7 ~/bin/terraform-1.5.7
bin install https://get.helm.sh/helm-v3.16.3-linux-amd64.tar.gz ~/bin/helm-3.16.3

Go Install

Configuration

Ensure go is present in your PATH.

Usage

bin runs go install <path>@<ref> into a private GOBIN, reads the installed version from the binary's build info and copies it to your dest. Your own GOPATH/bin or GOBIN is not touched.

The path can point at a package inside a module (for example cmd/<name>), go resolves the containing module. The ref defaults to latest and can be a tag, branch or commit; bin update follows that ref, so @main tracks the branch and @v0.1.8 stays put.

bin install goinstall://github.com/jrhouston/tfk8s@v0.1.8
bin install goinstall://github.com/googleapis/api-linter/v2/cmd/api-linter

Version resolution goes through the go toolchain, so GOPROXY, GOPRIVATE and GOFLAGS are honoured.

🔧 Configuration

Configuration file

bin maintains a configuration file to track installed binaries.

Linux/MacOS

Path to the configuration directory respects the XDG Base Directory specification using the following strategy:

• Honor BIN_CONFIG is set
• To prevent breaking of existing configurations, check if $HOME/.bin/config.json exists and return $HOME/.bin
• If XDG_CONFIG_HOME is set, return $XDG_CONFIG_HOME/bin
• If $HOME/.config exists, return $home/.config/bin
• Default to $HOME/.bin/

Windows

Same than linux but uses %USERPROFILE% without XDG_CONFIG_HOME.

Binary Storage

By default, bin stores binaries in:

• Linux/macOS: ~/.local/bin/
• Windows: %LOCALAPPDATA%\bin\

Ensure this directory is in your $PATH.

🤝 Contributing

There are some bugs, and the code has not been tested due to a lack of time, but contributions are welcome, and I’ll be happy to discuss and review them.

• Report bugs or request features via GitHub Issues
• Submit pull requests for improvements
• Update documentation

Development Setup

# Clone the repository
git clone https://github.com/marcosnils/bin.git
cd bin

# Clean and init
make clean download

# Run syntax check
make lint verify

# Run tests
make test

# Build from source
make build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📋 Rationale

bin started as an idea given the popularity of single binary releases due to the surge of languages like Go, Rust, Deno, etc which can easily produce dynamically and statically compiled binaries.

I found myself downloading binaries (or tarballs) directly from VCS (Github mostly) and then it was hard to keep control and update such dependencies whenever a new version was released. So, with the objective to solve that problem and also looking for something that will allow me to get the latest releases, I created bin.

In addition to that, I was also looking for something that doesn't require sudo or root privileges to install these binaries as downloading, making them executable and storing it somewhere in your PATH would be sufficient.

After I finished the first MVP, a friend pointed out that brew was now supported in linux which almost made me abandon the project. After checking out brew (never been an osx user), I found it a bit bloated and seems to be doing way more than what I'm actually needing. So, I've decided to continue bin and hopefully add more features that could result useful to someone else.