diff --git a/README.md b/README.md index 1030a50..5bc3fb5 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,177 @@ # binst -A collection of installation scripts for binary tools, generated using [binstaller](https://github.com/binary-install/binstaller). These scripts are portable POSIX shell scripts that work across Linux, macOS, and Windows (Git Bash/WSL) and are designed to be a simple, secure way to install self-contained binaries from GitHub releases. +A curated collection of portable installation scripts for binary tools, powered by [binstaller](https://github.com/binary-install/binstaller). -* [Quick Start](#quick-start) -* [Workflows](#workflows) - * [Creating New Installation Scripts](#creating-new-installation-scripts) -* [Notes](#notes) - * [Binary Names](#binary-names) +## Overview + +This repository provides POSIX-compliant shell scripts that simplify the installation of popular binary tools from GitHub releases. Each script is: + +- **Portable**: Works across Linux, macOS, and Windows (Git Bash/WSL) +- **Secure**: Includes checksum verification for downloaded binaries +- **Simple**: Single command installation with no dependencies +- **Self-contained**: No package manager or runtime required + +## Table of Contents + +- [Quick Start](#quick-start) +- [Available Tools](#available-tools) +- [Usage](#usage) + - [Installing Binaries](#installing-binaries) + - [Using Task Commands](#using-task-commands) +- [Creating New Scripts](#creating-new-scripts) + - [Prerequisites](#prerequisites) + - [Automatic Generation](#automatic-generation) + - [Manual Configuration](#manual-configuration) +- [Configuration](#configuration) + - [Binary Names](#binary-names) +- [Contributing](#contributing) +- [License](#license) ## Quick Start -Install any binary using its generated script: +Install any binary directly using its installation script: ```bash -# install trufflehog -$ scripts/trufflehog-install.sh +# Install trufflehog +./scripts/trufflehog-install.sh -# install task -$ scripts/task-install.sh +# Install task +./scripts/task-install.sh + +# Install checkov +./scripts/checkov-install.sh ``` -## Workflows +Binaries are installed to `~/.local/bin` by default (customizable via environment variables). -Common workflows for the creation, maintenance, usage of the installation scripts are encapsulated in [Task](https://taskfile.dev) tasks. +## Available Tools + +Installation scripts are located in the `scripts/` directory. Run `ls scripts/` to see all available tools, or browse the directory on GitHub. + +## Usage + +### Installing Binaries + +Run any installation script directly: ```bash -# list available tasks -$ task --list - -task: Available tasks for this project: -* default: Create a new installation script for a binary -* embed-checksums: Embed checksums into a binst configuration file. -* gen: Generate installation script from binst configuration. -* init: Initialize binst configuration for a GitHub project. -* install-*: Install a binary using its installation script. -* latest-release: Determine the latest release available for a given repo. - -# install a binary -$ task install-trufflehog +./scripts/-install.sh ``` -### Creating New Installation Scripts +The script will: +1. Detect your OS and architecture +2. Download the latest release from GitHub +3. Verify checksums +4. Install the binary to your PATH -The default task uses binstaller to creates a new installation script for a binary from -its GitHub repository. This is often the only step needed to add a new installation -script to the collection. +### Using Task Commands + +This repository includes [Taskfile](https://taskfile.dev) automation for common workflows: -To install binstaller, run: ```bash -$ scripts/binstaller-install.sh +# List all available tasks +task --list + +# Install a specific binary via Task +task install-trufflehog +task install-aichat +task install-checkov ``` -To create a new installation script: +Available tasks: +- `task` - Create a new installation script (requires `REPO` variable) +- `task install-*` - Install a binary using its script +- `task init` - Initialize binstaller configuration for a GitHub project +- `task embed-checksums` - Embed checksums into a configuration file +- `task gen` - Generate installation script from configuration +- `task latest-release` - Check the latest release version + +## Creating New Scripts + +### Prerequisites + +First, install binstaller: + ```bash -# create a new installation script by providing the GitHub repository as an argument: -$ task REPO=owner/repo-name - -# detailes summary -$ task --summary -task: default - -Create a new installation script for a binary by initializing a binst config, -embedding checksums, and generating the installation script. The latest release, as -determined by the latest-release task, will be used unless a specific version is -provided. - -Invoke this task like: - task default REPO=trufflesecurity/trufflehog - -vars: - CONFIG_DIR: "./config" - SCRIPT_DIR: "./scripts" - BINARY: "{{.REPO | base}}" - VERSION: "latest" - -requires: - vars: - - REPO - -commands: - - Task: init - - Task: embed-checksums - - Task: gen +./scripts/binstaller-install.sh ``` -## Notes +### Automatic Generation + +The easiest way to add a new installation script is using the default Task workflow: + +```bash +# Create script for a GitHub repository +task REPO=owner/repo-name + +# Example: Add installation script for trufflehog +task REPO=trufflesecurity/trufflehog +``` + +This command will: +1. Initialize a binstaller configuration file +2. Fetch and embed checksums from the latest release +3. Generate the installation script + +For more details on the default task: + +```bash +task --summary +``` + +### Manual Configuration + +For advanced use cases, you can manually create or edit configuration files: + +1. **Initialize configuration**: + ```bash + task init REPO=owner/repo-name + ``` + +2. **Edit the configuration** in `config/repo-name.binstaller.yml` as needed + +3. **Embed checksums**: + ```bash + task embed-checksums BINARY=repo-name + ``` + +4. **Generate the script**: + ```bash + task gen BINARY=repo-name + ``` + +## Configuration ### Binary Names -Sometimes the binary executable name differs from the GitHub repository name. When this occurs, the `asset.binaries` section in the configuration file defines the actual binary name. If this is the case, the generated installation script will need to be manually edited. +In some cases, the binary executable name differs from the GitHub repository name. When this occurs, specify the actual binary name in the `asset.binaries` section of the configuration file. -As an example, the released artifact for [stacklok/toolhive](https://github.com/stacklok/toolhive) is named `thv` rather than `toolhive`. The [configuration file](config/toolhive.binstaller.yml) specifies the correct name for the binary in the `asset.binaries` section. +**Example**: The [stacklok/toolhive](https://github.com/stacklok/toolhive) repository releases a binary named `thv`. The [configuration file](config/toolhive.binstaller.yml) handles this: ```yaml repo: stacklok/toolhive asset: -binaries: - - name: thv - path: thv + binaries: + - name: thv + path: thv ``` +After generation, you may wish to rename the installation script from `thv-install.sh` to `toolhive-install.sh` for consistency. + +## Contributing + +Contributions are welcome! To add a new binary installation script: + +1. Fork this repository +2. Create a new script using `task REPO=owner/repo-name` +3. Test the installation script +4. Submit a pull request + +Please ensure: +- The binary is a popular, well-maintained tool +- The installation script works across all supported platforms +- Checksums are embedded for security + ## License + MIT. See [LICENSE](LICENSE) for details.