{"id":13509116,"url":"https://github.com/devops-works/binenv","last_synced_at":"2025-05-16T09:03:19.059Z","repository":{"id":38019998,"uuid":"288517523","full_name":"devops-works/binenv","owner":"devops-works","description":"One binary to rule them all. Manage all those pesky binaries (kubectl, helm, terraform, ...) easily.","archived":false,"fork":false,"pushed_at":"2025-05-13T13:20:00.000Z","size":2100,"stargazers_count":390,"open_issues_count":23,"forks_count":46,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2025-05-13T14:41:34.824Z","etag":null,"topics":["binaries","golang","helm","installer","kubectl","uninstalling-versions"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devops-works.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-18T17:14:49.000Z","updated_at":"2025-05-13T13:20:05.000Z","dependencies_parsed_at":"2023-09-28T02:31:09.000Z","dependency_job_id":"998befcb-9c28-45e1-bb11-6a3276a91e3e","html_url":"https://github.com/devops-works/binenv","commit_stats":null,"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-works%2Fbinenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-works%2Fbinenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-works%2Fbinenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devops-works%2Fbinenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devops-works","download_url":"https://codeload.github.com/devops-works/binenv/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501555,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binaries","golang","helm","installer","kubectl","uninstalling-versions"],"created_at":"2024-08-01T02:01:03.154Z","updated_at":"2025-05-16T09:03:19.049Z","avatar_url":"https://github.com/devops-works.png","language":"Go","readme":"# binenv\n\nThe last binary you'll ever install.\n\n- [binenv](#binenv)\n  - [What](#what)\n  - [Quick start](#quick-start)\n    - [Linux (bash/zsh)](#linux-bashzsh)\n    - [MacOS (with bash)](#macos-with-bash)\n    - [Windows](#windows)\n    - [FreeBSD (bash/zsh)](#freebsd-bashzsh)\n    - [OpenBSD (bash/zsh)](#openbsd-bashzsh)\n  - [Install](#install)\n    - [User install](#user-install)\n  - [Updating binenv](#updating-binenv)\n  - [Supported \"distributions\"](#supported-distributions)\n  - [Usage](#usage)\n    - [Updating available distributions versions](#updating-available-distributions-versions)\n      - [Updating versions using a token](#updating-versions-using-a-token)\n      - [Update available distributions](#update-available-distributions)\n      - [Examples](#examples)\n    - [Searching distributions](#searching-distributions)\n    - [Installing new versions](#installing-new-versions)\n      - [Examples](#examples-1)\n    - [Listing versions](#listing-versions)\n      - [Examples](#examples-2)\n      - [Freezing versions](#freezing-versions)\n    - [Uninstalling versions](#uninstalling-versions)\n      - [Examples](#examples-3)\n    - [Completion](#completion)\n    - [Expanding binary absolute path](#expanding-binary-absolute-path)\n      - [Example](#example)\n    - [Upgrading all installed distributions](#upgrading-all-installed-distributions)\n  - [Selecting versions](#selecting-versions)\n    - [Version selection process](#version-selection-process)\n    - [Install versions form .binenv.lock](#install-versions-form-binenvlock)\n      - [Example](#example-1)\n    - [Adding versions to `.binenv.lock`](#adding-versions-to-binenvlock)\n  - [Environment variables](#environment-variables)\n  - [Removing binenv stuff](#removing-binenv-stuff)\n  - [Status](#status)\n  - [FAQ](#faq)\n    - [I installed a binary but is still see the system (or wrong) version](#i-installed-a-binary-but-is-still-see-the-system-or-wrong-version)\n    - [After installing a distribution, I get a \"shim: no such file or directory\"](#after-installing-a-distribution-i-get-a-shim-no-such-file-or-directory)\n    - [It does not work with sudo !](#it-does-not-work-with-sudo-)\n    - [I don't like binenv, are there alternatives ?](#i-dont-like-binenv-are-there-alternatives-)\n  - [Distributions file format](#distributions-file-format)\n    - [Distributions file reference](#distributions-file-reference)\n    - [Distributions file example](#distributions-file-example)\n  - [Caveats](#caveats)\n  - [Contributions](#contributions)\n  - [Licence](#licence)\n\n## What\n\n`binenv` will help you download, install and manage the binaries programs (we\ncall them \"distributions\") you need in you everyday DevOps life (e.g. kubectl,\nhelm, ...).\n\nThink of it as a `tfenv` + `tgenv` + `helmenv` + ...\n\nNow you can install your [favorite utility](#supported-distributions) just by\ntyping `binenv install something`.\n\n## Quick start\n\nSee [System-wide installation](./SYSTEM.md) for system-wide installations\n(a.k.a. global mode).\n\n### Linux (bash/zsh)\n\n```\nwget -q https://github.com/devops-works/binenv/releases/download/v0.19.11/binenv_linux_amd64\nwget -q https://github.com/devops-works/binenv/releases/download/v0.19.11/checksums.txt\nsha256sum  --check --ignore-missing checksums.txt\nmv binenv_linux_amd64 binenv\nchmod +x binenv\n./binenv update\n./binenv install binenv\nrm binenv\nif [[ -n $BASH ]]; then ZESHELL=bash; fi\nif [[ -n $ZSH_NAME ]]; then ZESHELL=zsh; fi\necho $ZESHELL\necho -e '\\nexport PATH=~/.binenv:$PATH' \u003e\u003e ~/.${ZESHELL}rc\necho \"source \u003c(binenv completion ${ZESHELL})\" \u003e\u003e ~/.${ZESHELL}rc\nexec $SHELL\n```\n\n### MacOS (with bash)\n\n```\nwget -q https://github.com/devops-works/binenv/releases/download/v0.19.11/binenv_darwin_amd64\nwget -q https://github.com/devops-works/binenv/releases/download/v0.19.11/checksums.txt\nsha256sum  --check --ignore-missing checksums.txt\nmv binenv_darwin_amd64 binenv\nchmod +x binenv\n./binenv update\n./binenv install binenv\nrm binenv\necho -e '\\nexport PATH=~/.binenv:$PATH' \u003e\u003e ~/.bashrc\necho 'source \u003c(binenv completion bash)' \u003e\u003e ~/.bashrc\nexec $SHELL\n```\n\n### Windows\n\nbinenv does not support windows.\n\n### FreeBSD (bash/zsh)\n\n```\nfetch https://github.com/devops-works/binenv/releases/download/v0.19.11/binenv_freebsd_amd64\nfetch https://github.com/devops-works/binenv/releases/download/v0.19.11/checksums.txt\nshasum --ignore-missing -a 512 -c checksums.txt\nmv binenv_freebsd_amd64 binenv\nchmod +x binenv\n./binenv update\n./binenv install binenv\nrm binenv\nif [[ -n $BASH ]]; then ZESHELL=bash; fi\nif [[ -n $ZSH_NAME ]]; then ZESHELL=zsh; fi\necho $ZESHELL\necho -e '\\nexport PATH=~/.binenv:$PATH' \u003e\u003e ~/.${ZESHELL}rc\necho \"source \u003c(binenv completion ${ZESHELL})\" \u003e\u003e ~/.${ZESHELL}rc\nexec $SHELL\n```\n\nIf you are using a different shell, skip adding completion to your `.${SHELL}rc` file.\n\nTo be able to verify checksums, you have to install the `p5-Digest-SHA` package.\n\n### OpenBSD (bash/zsh)\n\n```\nftp https://github.com/devops-works/binenv/releases/download/v0.19.11/binenv_openbsd_amd64\nftp https://github.com/devops-works/binenv/releases/download/v0.19.11/checksums.txt\ncksum -a sha256 -C checksums.txt binenv_openbsd_amd64\nmv binenv_openbsd_amd64 binenv\nchmod +x binenv\n./binenv update\n./binenv install binenv\nrm binenv\nif [[ -n $BASH ]]; then ZESHELL=bash; fi\nif [[ -n $ZSH_NAME ]]; then ZESHELL=zsh; fi\necho $ZESHELL\necho -e '\\nexport PATH=~/.binenv:$PATH' \u003e\u003e ~/.${ZESHELL}rc\necho \"source \u003c(binenv completion ${ZESHELL})\" \u003e\u003e ~/.${ZESHELL}rc\nexec $SHELL\n```\n\nIf you are using a different shell, skip adding completion to your `.${SHELL}rc` file.\n\n## Install\n\n### User install\n\n- download a suitable `binenv` (yes, but wait !) for your architecture/OS at\nhttp://github.com/devops-works/binenv/releases.\n\n```\nwget -q https://github.com/devops-works/binenv/releases/download/v0.19.11/binenv_\u003cOS\u003e_\u003cARCH\u003e\n```\n\n- rename it\n\n```\nmv binaryname binenv\n```\n\n- make it executable\n\n```\nchmod +x binenv\n```\n\n- execute an update\n\n```\n./binenv update\n```\n\n- now install `binenv` with `binenv` (so meta)\n\n```\n./binenv install binenv \u003cversion\u003e\n```\n\n- you can now remove the downloaded file\n\n```\nrm binenv\n```\n\n- prepend `~/.binenv` to your path in your `~/.bashrc` or `~/.zshrc` or ...\n\n```\nexport PATH=~/.binenv:$PATH\n```\n\n- while you're at it, install the completion (replace `bash` with your shell)\n\n```\nsource \u003c(binenv completion bash)\n```\n\n- \"restart\" your shell\n\n```\nexec $SHELL\n```\n\nSee a walkthough on asciinema.org:\n[![asciicast](https://asciinema.org/a/LmYClC9sVgNs24QZjKIFccFh4.svg)](https://asciinema.org/a/LmYClC9sVgNs24QZjKIFccFh4)\n\n## Updating binenv\n\nJust run `binenv install binenv`\n\nThis is the whole point.\n\n## Supported \"distributions\"\n\nFor the whole list of supported binaries (a.k.a. distributions), see\n[DISTRIBUTIONS.md](DISTRIBUTIONS.md).\n\nThe always up-to-date list is\n[here](https://github.com/devops-works/binenv/blob/master/distributions/distributions.yaml).\n\nThe list can be generated as markdown using `make distributions`.\n\nOpen an issue (or send a PR) if you need one that is not in the list.\n\n## Usage\n\n### Updating available distributions versions\n\nIn order to update the list of installable version for distributions, you need\nto update the version list (usually located in `$XDG_CONFIG/cache.json` or\n`~/.config/binenv/cache.json`).\n\nThis is done automatically when invoking `binenv update`.\n\nWithout arguments, it will fetch the cache from this repo. This cache is\ngenerated automatically daily.\n\nUsing the `-f` argument, `binenv` will retrieve available versions for _all_\ndistributions (watch out for Github API rate limits, [but see\nbelow](#updating-versions-from-generated-cache)).\n\nWith a distribution passed as an argument (e.g. `binenv update kubectl`), it\nwill only update installable versions for `kubectl`.\n\nWhen updating the cache, you can control fetch concurrency using the `-c` flag.\nIt defaults to 8 which is already pretty high. Do go crazy. This setting is\nmainly used to set a lower concurrency and be nice to GitHub.\n\nNote that Github enforces rate limits (e.g. 60 unauthenticated API requests per\nhours). So you should update all distributions (e.g. `binenv update -f`) with\ncaution. `binenv` will stop updating distributions when you only have 4\nunauthenticated API requests left.\n\n[GitHub tokens](#updating-versions-using-a-token) are also supported to avoid\nbeing rate-limited and fetch releases from their respective sources.\n\n#### Updating versions using a token\n\nTo avoid being rate limited, you can also use a personal access token.\n\n- go to [Settings/Personal Access Tokens/New personal access token](https://github.com/settings/tokens/new?description=GitHunt\u0026scopes=public_repo)\n- click \"Generate token\"\n\nTo use the token, just export it in the GITHUB_TOKEN environment variable:\n\n```bash\nexport GITHUB_TOKEN=aaa...bbb\n```\n\n#### Update available distributions\n\nDistributions are maintained in this\n[file](https://github.com/devops-works/binenv/blob/master/distributions/distributions.yaml).\n\nTo benefit from new additions, you need to update the distribution list from\ntime to time.\n\nThis list is usually located in your home directory under\n`$XDG_CONFIG/distributions.yaml` (often `~/.config/binenv/distribution.yaml`).\n\nTo update only distributions:\n\n```bash\nbinenv update --distributions # or -d\n```\n\nTo update distributions **and** their versions:\n\n```bash\nbinenv update --all # or -a\n```\n\n##### Using custom distributions file (and private GitLab repos)\n\nIf you want to use a custom distributions file, you can add a `.yaml` file in\nthe `$XDG_CONFIG` directory (often `~/.config/binenv/`).\n\nThis file will be merged with the default distributions file.\n\nNote that files are evaluated in lexicographical order, so if you want to\noverride a default, you should name your file accordingly.\n\nYou can use this mechanism to install binaries from private GitLab repositories\n(GitHub not supported right now). If you need to pass a `PRIVATE-TOKEN` in the\nheaders, you need to set the `token_env` key in the `list` and `fetch`\nsections. This key should contain the name of the environment variable that is\nset with the token.\n\nHere is an example file:\n\n```yaml\n$ cat ~/.config/binenv/distributions-custom.yaml\n---\nsources:\n  foo:\n    description: This tool let's you foo database tables\n    url: https://gitlab.exemple.org/infrastructure/tools/foo\n    list:\n      type: gitlab-releases\n      url: https://gitlab.example.org/api/v4/projects/42/releases\n      token_env: FOO_PRIVATE_TOKEN\n    fetch:\n      url: https://gitlab.example.org/api/v4/projects/42/packages/generic/foo/{{ .Version }}/foo-{{.OS }}-{{ .Arch }}-{{ .Version }}.gz\n      token_env: FOO_PRIVATE_TOKEN\n    install:\n      type: gzip\n      binaries:\n        - \"foo-{{.OS }}-{{ .Arch }}-{{ .Version }}.gz\"\n```\n\nYou will have to `export FOO_PRIVATE_TOKEN=your_token` before running `binenv`\nto make the token available.\n\n#### Examples\n\n- `binenv update`: update available versions for all distributions from github\n  cache\n- `binenv update -f`: update available versions for all distributions from all\n  releases\n- `binenv update -d`: update available distributions\n- `binenv update kubectl helm`: update available versions for `kubectl` and\n  `helm`\n\n### Searching distributions\n\nThe `search` command lets you search a distribution by name or description:\n\n```bash\n$ binenv search kube\nbinenv: One binary to rule them all. Manage all those pesky binaries (kubectl, helm, terraform, ...) easily.\nhelm: The Kubernetes Package Manager\nhelmfile: Deploy Kubernetes Helm Charts\nk9s: Kubernetes CLI To Manage Your Clusters In Style!\nketall: Like `kubectl get all`, but get really all resources\n... (lots of things with \"kube\" in it)\n```\n\n### Installing new versions\n\nAfter updating the list, you might want to install a shiny new version. No\n problem,`binenv install` has you covered.\n\nIf you want the latest non-prerelease version for something, just run:\n\n`binenv install something`\n\nIf you want a specific version:\n\n`binenv install something 1.2.3`\n\nNote that completion works, so don't be afraid to use it.\n\nYou can also install several distribution versions at the same time:\n\n`binenv install something 1.2.3 somethingelse 4.5.6`\n\nUsing the `--dry-run` flag (a.k.a `-n`) will show what would be installed.\n\n#### Examples\n\n- `binenv install kubectl`: install latest non-prerelease `kubectl version`\n- `binenv install kubectl 1.18.8`: install `kubectl` version 1.18.8\n- `binenv install kubectl 1.18.8 helm 3.3.0`: install `kubectl` version 1.18.8\n  and `helm` 3.3.0\n\n### Listing versions\n\nYou can list available, installed and activated distribution versions using\n`binenv versions`.\n\nWhen invoked without arguments, all version of all distributions will be printed.\n\nWith distributions as arguments, only versions for those distributions will be\nprinted.\n\nIn the output, versions printed in reverse mode are the currently selected\n(a.k.a. active) versions (see [Selecting versions](#selecting-versions) below.\n\nVersions in **bold** are installed.\n\nAll other versions are available to be installed.\n\n#### Examples\n\n```\n$ binenv versions\nterraform: 0.13.1 (/home/you/some/dir) 0.13.0 0.13.0-rc1 0.13.0-beta3 0.13.0-beta2 0.13.0-beta1 0.12.29 0.12.28 0.12.27 0.12.26 0.12.25 0.12.24 0.12.23 0.12.22 0.12.21 0.12.20 0.12.19 0.12.18 0.12.17 0.12.16 0.12.15 0.12.14 0.12.13 0.12.12 0.12.11 0.12.10 0.12.9 0.12.8 0.12.7 0.12.6\nterragrunt: 0.23.38 0.23.37 0.23.36 0.23.35 0.23.34 0.23.33 0.23.32 0.23.31 0.23.30 0.23.29 0.23.28 0.23.27 0.23.26 0.23.25 0.23.24 0.23.23 0.23.22 0.23.21 0.23.20 0.23.19 0.23.18 0.23.17 0.23.16 0.23.15 0.23.14 0.23.13 0.23.12 0.23.11 0.23.10 0.23.9\ntoji: 0.2.4 (default) 0.2.2\nvault: 1.5.3 1.5.2 1.5.1 1.5.0 1.5.0-rc 1.4.6 1.4.5 1.4.4 1.4.3 1.4.2 1.4.1 1.4.0 1.4.0-rc1 1.4.0-beta1 1.3.10 1.3.9 1.3.8 1.3.7 1.3.6 1.3.5 1.3.4 1.3.3 1.3.2 1.3.1 1.3.0 1.3.0-beta1 1.2.7 1.2.6 1.2.5 1.2.4\n...\n```\n\n(the output above does not show bold or reverse terminal output)\n\n#### Freezing versions\n\nWhen the `versions` command is invoked with the `--freeze` option, it will\nwrite a `.binenv.lock` style file on stdout.\n\nThis way you can \"lock\" the dependencies for your project just by issuing:\n\n```\ncd myproject\nbinenv versions --freeze \u003e .binenv.lock\n```\n\nYou can the commit this file to your project so everyone will use the same\ndistributions versions when in this repository. See [Selecting Versions](#selecting-versions) for more information on this file.\n\nNote that currently selected versions for _all_ distributions will be\noutputted. You might want to trim stuff you do not use from the file.\n\n### Uninstalling versions\n\nIf you need to clean up a bit, you can uninstall a specific version, or all\nversions for a distribution. In the latter case, a confirmation will be asked.\n\nThe command accepts:\n- a single argument (remove all versions for distributions)\n- an even count of arguments (distribution / version pairs)\n\n#### Examples\n\n- `binenv uninstall kubectl 1.18.8 helm 3.3.0`: uninstall `kubectl` version\n  1.18.8 and `helm` 3.3.0\n- `binenv uninstall kubectl 1.18.8 kubectl 1.16.15`: uninstall `kubectl` versions\n  1.18.8 and 1.16.15\n- `binenv uninstall kubectl`: removes all `kubectl` versions\n\n### Completion\n\nInstall completion for your shell. See `binenv help completion` for in-depth\ninfo.\n\n### Expanding binary absolute path\n\nTo get the absolute path of the binary installed by a distribution you need to\ninvoke the command `expand`.\n\nThis can be useful when you need to use binenv in conjunction with other tools\nlike `sudo`.\n\n#### Example\n\n```bash\n$ binenv install yq\n2022-02-16T14:24:56-03:00 WRN version for \"yq\" not specified; using \"4.18.1\"\nfetching yq version 4.18.1 100% |████████████████████████████| (9.1/9.1 MB, 4.858 MB/s)\n2022-02-16T14:24:59-03:00 INF \"yq\" (4.18.1) installed\n$ binenv expand yq\n/Users/local-user/.binenv/binaries/yq/4.18.1\n$ sudo $(binenv expand yq) --version\nyq (https://github.com/mikefarah/yq/) version 4.18.1\n```\n\n### Upgrading all installed distributions\n\nTo upgrade all installed distributions to the last known version invoke the\ncommand `upgrade`\n\nThis command will always select the last version available and will ignore any\nversion selection previously made by the user.\n\n## Selecting versions\n\nTo specify which version to use, you have to create a `.binenv.lock` file in\nthe directory. Note that only **semver** is supported.\n\nThis file has the following structure:\n\n```\n\u003cdistributionA\u003e\u003cconstraintA\u003e\n\u003cdistributionB\u003e\u003cconstraintB\u003e\n...\n```\n\nFor instance:\n\n```\nkubectl=1.18.8\nterraform\u003e0.12\nterragrunt~\u003e0.23.0\n```\n\nYou can then commit the file in your project to ensure everyone in your team is\non the same page.\n\nThe constraint operators are:\n\n- `=`:  version must match exactly\n- `!=`: version must not match\n- `\u003e`:  version must be strictly higher\n- `\u003c`:  version must be strictly lower\n- `\u003e=`: version must be at least\n- `\u003c=`: version must be at most\n- `~\u003e`: version must be at least this one in the same but match the same minor\n  versions\n\n### Version selection process\n\nWhen you execute a distribution (e.g. you run `kubectl`), `binenv` runs it\nunder the hood. Before running it, it will check which version it should use.\nFor this, it will check for a `.binenv.lock` file in the current directory.\n\nIf none is found, it will check in the parent folder. No lock file ? Check in\nparent folder again. this process continues until `binenv` reaches your home\ndirectory (or `/` if run in global mode).\n\nIf no version requirements are found at this point, `binenv` will use the last\nnon-prerelease version installed.\n\n### Install versions form .binenv.lock\n\nInstall versions specified in `.binenv.lock` file, you can use the `--lock`\n(a.k.a. `-l`) flag.\n\n#### Example\n\n```bash\n$ cat .binenv.lock\nterraform\u003e0.13.0\nhelmfile\u003c0.125.0\nhadolint\u003c1.17.0\n$ binenv install -l\n2020-08-29T11:39:18+02:00 WRN installing \"terraform\" (0.13.1) to satisfy constraint \"terraform\u003e0.13.0\"\nfetching terraform version 0.13.1 100% |█████████████████████████████████████████████████████████████████████████████████████████████| (33/33 MB, 3.274 MB/s) [10s:0s]\n2020-08-29T11:39:29+02:00 WRN installing \"helmfile\" (0.124.0) to satisfy constraint \"helmfile\u003c0.125.0\"\nfetching helmfile version 0.124.0 100% |█████████████████████████████████████████████████████████████████████████████████████████████| (45/45 MB, 1.404 MB/s) [31s:0s]\n2020-08-29T11:40:02+02:00 WRN installing \"hadolint\" (1.16.3) to satisfy constraint \"hadolint\u003c1.17.0\"\nfetching hadolint version 1.16.3 100% |███████████████████████████████████████████████████████████████████████████████████████████| (3.5/3.5 MB, 431.886 kB/s) [8s:0s]\n$\n```\n\n### Adding versions to `.binenv.lock`\n\nTo populate the `.binenv.lock` file in the current directory, you can use the\n`local` command with the distributions and versions you want to add.\n\nFor instance:\n\n```bash\nbinenv local kubectl 1.30.0 helmfile 0.126.0\n```\n\nNote that this will update the `.binenv.lock` file and not replace it, so the\ncommand above is equivalent to:\n\n```bash\nbinenv local kubectl 1.30.0\nbinenv local helmfile 0.126.0\n```\n\nand produce the following `.binenv.lock` file:\n\n```bash\nkubectl=1.30.0\n\n\n### Selecting versions using environment variables\n\n_Introduced in v0.17.0_\n\nIn addition to using the .binenv.lock file, it is possible to define the\ndistribution version using an environment variable of the form\n`BINENV_\u003cDISTRIBUTION\u003e_VERSION=\u003cCONSTRAINT\u003e`.\n\nWhen an environment variable with this name exists, binenv will use the `=`\noperator to look for an exact match for that constraint and will ignore the\ncontents of the `.binenv.lock` file if it exists.\n\n#### Example\n\n```bash\n$ cat .binenv.lock\nhelm=3.7.2\n\n$ helm version\nversion.BuildInfo{Version:\"v3.7.2\", GitCommit:\"663a896f4a815053445eec4153677ddc24a0a361\", GitTreeState:\"clean\", GoVersion:\"go1.16.10\"}\n\n$ BINENV_HELM_VERSION=3.6.3 helm version\nversion.BuildInfo{Version:\"v3.6.3\", GitCommit:\"d506314abfb5d21419df8c7e7e68012379db2354\", GitTreeState:\"clean\", GoVersion:\"go1.16.5\"}\n```\n\n## Environment variables\n\nOther environment variables exists to control `binenv` behavior:\n\n- `BINENV_GLOBAL`: forces `binenv` to run un global mode (same as `-g`); see\n  [SYSTEM.md](./SYSTEM.md) for more information on this mode.\n- `BINENV_VERBOSE`: same as `-v`\n- `BASH_COMP_DEBUG_FILE`: if set, will write debug information for bash\n  completion to this file\n\n## Removing binenv stuff\n\n`binenv` stores\n\n- downloaded binaries by default in `~/.binenv/binaries`\n- the versions cache in `~/.cache/binenv/` (or wherever your `XDG_CACHE_HOME` variable points to)\n- the list of known distributions in `~/.config/binenv/` (or wherever your `XDG_CONFIG_HOME` variable points to).\n\nTo wipe everything clean:\n\n```bash\nrm -rfi ~/.binenv ~/.config/binenv ~/.cache/binenv\n```\n\nDon't forget to remove the `PATH` and the completion you might have changed in\nyour shell rc file.\n\n## Status\n\nThis is really _super alpha_ and has only be tested on Linux \u0026 MacOS. YMMV on\nother platforms.\n\nThere are **no tests**. I will probably go to hell for this.\n\n## FAQ\n\n### I installed a binary but is still see the system (or wrong) version\n\nTry to rehash your binaries (`hash -r` in bash or `rehash` in Zsh).\n\n### After installing a distribution, I get a \"shim: no such file or directory\"\n\nIf you see something like:\n\n```\n2020-11-10T09:01:20+01:00 ERR unable to install \"kubectl\" (1.19.3) error=\"unable to find shim file: stat /Users/foo/.binenv/shim: no such file or directory\"\n```\n\nyou probably did not follow the [installation instructions](#quick-start).\n\nRunning `./binenv update binenv \u0026\u0026 ./binenv install binenv` should correct the\nproblem.\n\n### It does not work with sudo !\n\nYes, for not we'restuckon this one. You still can reference thereal binary\ndirectly:\n\n```bash\nsudo ~/.binenv/binaries/termshark/2.2.0\n```\n\n### I don't like binenv, are there alternatives ?\n\nSorry to hear that. Don't hesitate opening an issue or sending a PR is\nsomething does not fit your use case\n\nA nice alternative exists:\n\n- https://asdf-vm.com/\n\n## Distributions file format\n\n[distributions.yaml](https://github.com/devops-works/binenv/blob/develop/distributions/distributions.yaml)\ncontains all the distributions supported by `binenv`, and how to fetch them. It\nis written in YAML and is defined by the scheme below.\n\n### Distributions file reference\n\n```yaml\nsources:\n\n  # Name of the distribution\n  \u003cstring\u003e:\n\n    # Description provided by the binary author(s).\n    description: \u003cstring\u003e\n\n    # URL for binary (usually homepage or repository).\n    url: \u003curl\u003e\n\n    # Post install message shown after successful installation\n    # Use `post_install_message: |` for multi-line messages\n    post_install_message: \u003cstring\u003e\n\n    # map creates aliases between architectures known by binenv and those\n    # expected by the original author(s).\n    # Check `bat` distribution for a more meaningful example.\n    [map: \u003cmap_config\u003e]\n\n    # list contains the kind of releases and where to fetch their\n    # history.\n    list:\n\n      # Type of the releases.\n      # One of \"static\", \"github-releases\", \"gitlab-releases\"\n      type: \u003cstring\u003e\n\n      # Where to fetch the releases.\n      # I.e. https://github.com/devops-works/binenv/releases\n      url: \u003cstring\u003e\n\n    # fetch holds the URL from where the binaries can be downloaded.\n    fetch:\n\n      # Templatised URL to the binary. Values to templatise can be:\n      # Host architecture with {{ .Arch }}, operating system with {{ .OS }},\n      # version with {{ .Version }}, sometimes .exe with {{ .ExeExtension}}.\n      url: \u003cstring\u003e\n\n    # Defines how to install the binary.\n    install:\n\n      # Type of installation. Can be :\n      # \"direct\" if after download the binary is executable as is;\n      # \"tgz\" if it needs to be uncompressed using tar and gzip;\n      # \"zip\" if it needs to be unzipped;\n      # \"tarx\" if it needs to be uncompressed with tar;\n      type: \u003cstring\u003e\n\n      # Name of the binar(y|ies) that will be downloaded\n      [binaries: \u003cbinaries_config\u003e]\n\n    # Supported platforms\n    [supported_platforms: \u003csupported_platforms\u003e]\n```\n\n`map_config`:\n\n```yaml\n# Alias to amd64 arch\n[amd64: \u003cstring\u003e]\n\n# Alias to i386 arch\n[i386: \u003cstring\u003e]\n\n# Alias to darwin arch\n[darwin: \u003cstring\u003e]\n\n# Alias to linux arch\n[linux: \u003cstring\u003e]\n\n# Alias to windows arch\n[windows: \u003cstring\u003e]\n```\n\n`binaries_config`:\n\n```yaml\n# Array of binaries names that will be installed.\n# The string provided is treated as a regexp.\n# This regexp is compared to the filenames found in packages.\n# Note that filenames contains their path in the package with the top level\n# directory removed, e.g.:\n# software-13.0.0-x86_64-unknown-linux-musl/foo/bar/zebinary\n# becomes\n# foo/bar/zebinary\n# Also note that, since all binaries will be installed as the distribution\n# entry name, only one (the latest match) will survive for now.\n# The list is just here to allow alternate names, not real multiple binaries\n# installation.\n - \u003cregexp\u003e\n```\n\n`supported_platforms`:\n\n```yaml\n# Array of OS/Arch parirs\n# See: https://pkg.go.dev/runtime#pkg-constants\n- os: \u003cstring\u003e\n  arch: \u003cstring\u003e\n```\n\n### Distributions file example\n\n```yaml\nsources:\n  popeye:\n    description: A Kubernetes cluster resource sanitizer\n    url: https://github.com/derailed/popeye\n    map:\n      amd64: x86_64\n      darwin: Darwin\n      linux: Linux\n      windows: Windows\n    list:\n      type: github-releases\n      url: https://api.github.com/repos/derailed/popeye/releases\n    fetch:\n      url: https://github.com/derailed/popeye/releases/download/v{{ .Version }/popeye_{{ .OS }}_{{ .Arch }}.tar.gz\n    install:\n      type: tgz\n      binaries:\n        - popeye\n    supported_platforms:\n      - os: linux\n        arch: amd64\n      - os: windows\n        arch: amd64\n      - os: darwin\n        arch: amd64\n```\n\nThe `distributions.yaml` file used by default by `binenv` is located [here](https://github.com/devops-works/binenv/blob/develop/distributions/distributions.yaml), don't hesitate to have a look on it's structure.\n\n## Caveats\n\nSince `binenv` uses your PATH and HOME to find binaries and layout it's\nconfiguration files, using sudo with binenv-installed binaries is not very\nstraightforward. You can either install binenv as the root user (so it can find\nit's config), or pass those two environment variables when invoking sudo, like\nso:\n\n```\nsudo env \"PATH=$PATH\" \"HOME=$HOME\" binary_installed_with_binenv ...\n```\n\n## Contributions\n\nWelcomed !\n\nThanks to all contributors:\n\n- @alexanderbe-commit\n- @alenzen\n- @alex-bes\n- @angrox\n- @axgkl\n- @cleming\n- @Dazix\n- @deknos\n- @DnR-iData\n- @dundee\n- @eagafonov\n- @earzur\n- @eze-kiel\n- @gwenall\n- @harleypig\n- @iainelder\n- @jakubvokoun\n- @kenni-shin\n- @mpepping\n- @patsevanton\n- @pichouk\n- @pklejch\n- @semoac\n- @shr-project\n- @Sierra1011\n- @tm-drtina\n- @xx4h\n\n## Licence\n\nMIT\n","funding_links":[],"categories":["Go","golang"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevops-works%2Fbinenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevops-works%2Fbinenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevops-works%2Fbinenv/lists"}