eget(1)

📦 version 1.3.4, in nixos 26.05, nixpkgs unstable

eget(1) — the manual, but make it cute ✨

okay so bestie, this is eget — a tool for easily installing prebuilt binaries from GitHub. that's the whole vibe. 💅

SYNOPSIS

eget [--version] [--help] [OPTIONS] TARGET

DESCRIPTION

Eget is literally a tool for downloading and extracting prebuilt binaries from releases on GitHub. here's how it works: you give it a repository and Eget will search through the assets from the latest release, trying to find a suitable prebuilt binary for your system. if one is found, the asset gets downloaded and Eget extracts the binary to the current directory. 🎀

important vibe check: Eget should only be used for installing simple, static prebuilt binaries — like, where the extracted binary is all that's needed for installation. for more complex installation, you can use the --download-only option and do extraction manually. no cap. 🫶

The PROJECT argument passed to Eget should be one of these three things:

  • a GitHub repository, formatted as user/repo — in which case Eget will search the release assets
  • a direct URL — in which case Eget will directly download and extract from the given URL
  • a local file — in which case Eget will extract directly from the local file

If Eget downloads an asset called xxx and there also exists an asset called xxx.sha256 or xxx.sha256sum, Eget will automatically verify that the SHA-256 checksum of the downloaded asset matches the one contained in that file, and abort installation if a mismatch occurs. so dramatic, but honestly iconic. 💀

When installing an executable, Eget will place it in the current directory by default. if the environment variable EGET_BIN is non-empty, Eget will place the executable in that directory. the --to flag may also be used to customize the install location. ✨

Directories can also be specified as files to extract, and all files within them will be extracted. for example:

eget https://go.dev/dl/go1.17.5.linux-amd64.tar.gz --file go --to ~/go1.17.5

GitHub limits API requests to 60 per hour for unauthenticated users. if you wanna perform more requests (up to 5,000 per hour), you can set up a personal access token and assign it to an environment variable named either GITHUB_TOKEN or EGET_GITHUB_TOKEN when running Eget. if both are set, EGET_GITHUB_TOKEN will take precedence. Eget will read this variable and send the token as authorization with requests to GitHub. it's also possible to read the token from a file by using @/path/to/file as the token value. 🔑

The behavior of Eget is configurable in a number of ways via options. documentation for these options is provided below. 👇

OPTIONS ✨

  • -t, --tag= — use the given tagged release instead of the latest release. if the project doesn't have a tag that matches exactly, eget will look for a tag that contains the given string, and use the latest one. example: eget -t nightly zyedidia/micro. 🏷️
  • --pre-release — include pre-releases when fetching the latest version. this will get the latest overall release, even if it's a pre-release. 🧚
  • --source — download the source code for the repository (only works for GitHub repositories) rather than a release. downloads from the “master” branch by default. use --tag to download a different tag or branch. 🌿
  • --to= — move the executable to the given name after extraction. if the name is -, the data will be written to stdout. example: eget zyedidia/micro --to /usr/local/bin. example: eget --asset nvim.appimage --to nvim neovim/neovim. 📁
  • -s, --system= — use the given system as the target instead of the host. systems follow the notation `OS/Arch`, where OS is a valid OS (darwin, windows, linux, netbsd, openbsd, freebsd, android, illumos, solaris, plan9), and Arch is a valid architecture (amd64, 386, arm, arm64, riscv64). if the special value all is used, all possibilities are given and the user must select manually. example: eget -s darwin/amd64 zyedidia/micro. 🖥️
  • -f, --file= — extract the file that matches the given glob. you may want to use this option to extract non-binary files. example: eget -f LICENSE zyedidia/micro. 📄
  • --all — extract all candidate files. 💯
  • -q, --quiet — only print essential output. 🤫
  • --download-only — stop after downloading the asset. this prevents Eget from performing extraction, allowing you to perform manual installation after the asset is downloaded. ✋
  • --download-all — download all projects defined in the configuration file. 🗂️
  • --upgrade-only — only download the asset if the release is more recent than an existing asset with the same name in $EGET_BIN, or the current directory if $EGET_BIN is not defined. ⬆️
  • -a, --asset= — download a specific asset containing the given string. if there is an exact match with an asset, that asset is used regardless (except when using ^). if the argument begins with a ^, then any asset that does not match the argument is a candidate. this option can be specified multiple times for additional filtering. example: eget --asset nvim.appimage neovim/neovim. example: eget --download-only --asset amd64.deb --asset musl sharkdp/bat. if the assets are filterable using the --system detector (i.e., if applying the detector does not remove all candidates), the system detector is applied. use --system all to always consider all assets. 🎯
  • --sha256 — show the SHA-256 hash of the downloaded asset. this can be used to verify that the asset is not corrupted. 🔐
  • --verify-sha256= — verify the SHA-256 hash of the downloaded asset against the one provided as an argument. similar to --sha256, but Eget will do the verification for you. ✅
  • --rate — show GitHub API rate limiting information. 📊
  • --remove — remove the target file from $EGET_BIN (or the current directory if unset). note that this flag is boolean, and means eget will treat TARGET as a file to be removed. 🗑️
  • -k, --disable-ssl — disable SSL certificate verification for GET requests. cannot be used in combination with a GITHUB_TOKEN. ⚠️
  • -v, --version — show version information. ℹ️
  • -h, --help — show a help message. 🙋‍♀️

CONFIGURATION 🛠️

Eget can be configured using a TOML file located at ~/.eget.toml. alternatively, the configuration file can be located in the same directory as the Eget binary.

both global settings can be configured, as well as setting on a per-repository basis. sections can be named either global or "owner/repo", where owner and repo are the owner and repository name of the target repository (note that the owner/repo format is quoted). 📝

for example, the following configuration file will set the --to flag to ~/bin for all repositories, and will set the --to flag to ~/.local/bin for the zyedidia/micro repository:

[global]
target = "~/bin"

["zyedidia/micro"]
target = "~/.local/bin"

more complete example configuration:

[global]
    github_token = "ghp_1234567890"
    quiet = false
    show_hash = false
    upgrade_only = true
    target = "./test"

["zyedidia/micro"]
    upgrade_only = false
    show_hash = true
    asset_filters = [ "static", ".tar.gz" ]
    target = "~/.local/bin/micro"

by using the configuration above, you could run the following command to download the latest release of micro: eget zyedidia/micro. without the configuration, you would need to run the following command instead: eget zyedidia/micro --to ~/.local/bin/micro --sha256 --asset static --asset .tar.gz. 🎀

Available settings 🎛️

  • all — whether to extract all candidate files.
  • asset_filters — an array of partial asset names to filter the available assets for download.
  • download_only — whether to stop after downloading the asset (no extraction).
  • file — the glob to select files for extraction.
  • github_token — GitHub API token to use for requests.
  • quiet — whether to only print essential output.
  • show_hash — whether to show the SHA-256 hash of the downloaded asset.
  • system — the target system to download for.
  • target — the directory to move the downloaded file to after extraction.
  • upgrade_only — whether to only download if release is more recent than current version.

FOR MAINTAINERS 👑

to guarantee compatibility of your software’s pre-built binaries with Eget, you can follow these rules:

  • provide your pre-built binaries as GitHub release assets. 📦
  • format the system name as OS_Arch and include it in every pre-built binary name. supported OSes are darwin/macos, windows, linux, netbsd, openbsd, freebsd, android, illumos, solaris, plan9. supported architectures are amd64, i386, arm, arm64, riscv64. 🧬
  • if desired, include *.sha256 files for each asset, containing the SHA-256 checksum of each asset. these checksums will be automatically verified by Eget. 🔏
  • include only a single executable or appimage per system in each release archive. 🎯
  • use .tar.gz, .tar.bz2, .tar.xz, .tar, or .zip for archives. you may also directly upload the executable without an archive, or a compressed executable ending in .gz, .bz2, or .xz. 🗜️

if you don’t follow these rules, Eget may still work well with your software. Eget’s auto-detection is much more relaxed than what is required by these rules, but if you follow these rules your software is guaranteed to be compatible with Eget. 🤝

BUGS 🐛

See GitHub Issues: https://github.com/zyedidia/eget/issues

AUTHOR 🌟

Zachary Yedidia zyedidia@gmail.com

that's the whole manual, bestie. go forth and install some iconic prebuilt binaries. eget(1) out — Eget Manual, periodt. 💅✨🎀

📦 where this page comes from