Bina

An installer for self-contained, single-file binaries.

Install binaries from GitHub Releases.
No additional CLI required.

$ curl -fsSL https://bina.egoist.dev/denoland/deno | sh

==> Downloading github.com/denoland/deno@latest

==> Resolved version latest to v1.16.3

==> Downloading asset for darwin amd64

==> Installing deno to /usr/local/bin

==> Installation complete

$ deno

Deno 1.16.3

exit using ctrl+d or close()

> ▌

Introduction

Bina allows you to install CLI programs distributed via GitHub Releases, without the need for using a separate CLI, all you need is a single curl command.

For Users

Basic usage:

curl -fsSL https://bina.egoist.dev/$OWNER/$NAME | sh

The above command will install appropriate release from github.com/$OWNER/$NAME, by default we install it to /usr/local/bin directory, but you can change this by passing a query parameter dir like this:

curl -fsSL "https://bina.egoist.dev/$OWNER/$NAME?dir=./bin" | sh

This will then install the binary to ./bin directory instead.

If you want to install a specific version, you can append @$VERSION to the pathname:

curl -fsSL "https://bina.egoist.dev/$OWNER/$NAME@v1.2.3" | sh

More query parameters are available:

  • name: Custom binary name, by default it's the repo name.
  • token: GitHub personal token, if you want to install from a private repo. Alternatively you can pass the token via http header: curl -H "x-github-token:YOUR_TOKEN"
  • file: The name of the binary file in the asset, by default it's the same as repo name

Shortcut Command

Not a fan of typing a long curl command manually? You can use the npx tool instead if you have Node.js installed:

$ npx bina OWNER/NAME
Detailed CLI usages:
Usage:
  $ bina [repo]

Commands:
  [repo]  Install a binary from a repository

For more info, run any command with the `--help` flag:
  $ bina --help

Options:
  --token <gh_token>       Set a GitHub token to access private repos
  -d, --install-dir <dir>  Set the installation directory (default: /usr/local/bin)
  -n, --name <name>        Set the binary name (default: repo name)

For Maintainers

Bina automatically infers the asset name based on the user's OS and ARCH, but sometimes it can go wrong, because not everyone follows the same naming convention when publishing their assets, that's where the bina.json comes in.

To make Bina get the asset 100% correctly, you need to add a bina.jsonfile to your release assets like this:

{
  "platforms": {
    "darwin-amd64": {
      "asset": "my-program-darin-x86_64.tar.gz",
      "file": "bin/my-program"
    },
    "windows-amd64": {
      "asset": "my-program-windows-x86_64.tar.gz",
      "file": "bin/my-program.exe"
    }
  }
}

The platform name is a combination of OS and ARCH, where OS can be:

  • darwin
  • dragonfly
  • freebsd
  • linux
  • android
  • nacl
  • netbsd
  • openbsd
  • plan9
  • solaris
  • windows

And ARCH can be:

  • amd64
  • 386
  • arm64
  • armv5
  • armv6
  • armv7
  • ppc64
  • ppc64le
  • mips
  • mipsle
  • mips64
  • s390x
  • amd64p32

asset refers to the name of an asset in the release. Currently following archived files are supported:

  • .zip
  • .tar.gz
  • .tgz
  • .tar.xz
  • .txz
  • .tar.bz2
  • .tar.bz
  • .tar

file refers to the path to the binary file inside the archived asset.

FAQ

It shows 403 error or GitHub rate limit error

On our server, we call GitHub API to retrived repo release information, in the downloaded shell script it will call GitHub API to download the asset. The first one happens on our server, and the second one happens locally on your machine.

Sometimes it hits rate limit on the server side and shows server error in the error message, in this case you need to provide a GitHub personal token in the curl command via query parameter ?token=FOO or http header x-github-token=FOO.

Otherwise, it will be an error from the shell script you ran locally. Setting query paramater or http header will also fix this, but you can also use an environment variable GITHUB_TOKEN locally to avoid that, in this way the token will never be sent to our server.

Can I share the shell script?

Absolutely Yes, if you open https://bina.egoist.dev/$OWN/$REPO in your browser you can see the generated shell script, you can share the code with anyone. But please note that the query parameters will be hardcoded into the script, which means you should NOT share the script when using a ?token= query.

Sponsors

You can support this project via GitHub Sponsors.

github sponsors