gh-release-install

Download, extract, and install GitHub release assets from the terminal.

gh-release-install combines an interactive TUI and a scriptable CLI in one binary, with runtime-aware release/asset selection and safe archive handling.

Main Features

• Interactive and non-interactive workflows:
  • tui for guided installs
  • install for automation/scripts
• Smart defaults:
  • latest release is marked and preselected
  • release and asset auto-selection prefers current OS/architecture when possible
• Alias-aware asset matching (for example aarch64 -> arm64, x86_64 -> amd64)
• Archive extraction support: .zip, .tar, .tar.gz, .tgz
• Optional post-install symlink creation in TUI mode:
  • auto-detects executable files in installed content
  • lets you select one or more binaries
  • lets you choose the symlink destination directory
• Predictable install layout via categories:
  • single-bin-file
  • single-dir
  • multiple-files
• Safety checks:
  • path traversal in archives is rejected
  • symlinks are skipped during extraction/move operations

Quick Start

Build

Requires Go >= 1.25.7.

go build -o gh-release-install ./cmd/gh-release-install

Run interactive mode (default)

./gh-release-install --repo cli/cli --dest /opt/tools

# Equivalent explicit command:
./gh-release-install tui --repo cli/cli --dest /opt/tools

Run non-interactive mode

./gh-release-install install \
  --repo cli/cli \
  --version latest \
  --dest /opt/tools

Commands

tui (interactive)

./gh-release-install tui [--repo <owner/repo|github-url>] [--dest ./path] [--no-pretty]

• Default mode when you run ./gh-release-install with no subcommand.
• pretty UI is used by default (arrow keys + styled selection).
• Use --no-pretty for basic line prompts and broader terminal compatibility.
• After install, TUI can prompt to create symlinks for detected executable files.

install (non-interactive)

./gh-release-install install \
  --repo <owner/repo|github-url> \
  --dest ./path \
  [--version latest|<tag>] \
  [--asset <name>|--asset-index N] \
  [--overwrite]

• If multiple assets exist and neither --asset nor --asset-index is set, the installer tries to auto-select by current OS/arch.
• If auto-selection is ambiguous, the command exits with available assets and asks for explicit selection flags.

list

./gh-release-install list --repo <owner/repo|github-url>

Print release and asset listings for debugging or manual selection workflows.

Install Category Behavior

After download/extraction, content is classified and installed as:

1. single-bin-file One extracted file (or a non-archive asset). Creates a release directory (<repo>-<tag>) and places the file inside.
2. single-dir Exactly one extracted top-level directory. Moves that directory directly into destination.
3. multiple-files Multiple extracted top-level entries. Creates a release directory (<repo>-<tag>) and moves all entries inside.

Authentication (Optional)

For higher API limits or private repositories:

export GITHUB_TOKEN=<token>
./gh-release-install tui

You can also pass --token directly to tui, install, or list.

Notes

• If target path exists, set --overwrite to replace it.
• In install mode, --repo and --dest are required.
• --repo accepts either owner/repo or a GitHub URL (for example https://github.com/owner/repo).
• --dest accepts relative paths, absolute paths, and ~ home shortcuts (for example ~/tools).