> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Install script

> How the install.sh script works and its configuration options.

`install.sh` is a POSIX `sh` script that fetches the correct Buttons binary for your platform, verifies its integrity against the release `checksums.txt`, and installs it. It works on macOS and Linux — anywhere `/bin/sh` is available, including Alpine, Debian slim, and other BusyBox-based container images.

## Basic usage

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh | sh
```

<Note>
  While the `autonoco/buttons` repository is private, the script downloads release
  assets through the authenticated GitHub API, so you must export a `GITHUB_TOKEN`
  with `contents:read` scope first. Once the repository is public this token
  becomes optional (it only raises the API rate limit).

  ```bash theme={null}
  curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh \
    | GITHUB_TOKEN=$GH_TOKEN sh
  ```
</Note>

## Configuration via environment variables

Pass variables before `sh` to control the install:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh \
  | BUTTONS_VERSION=v0.128.0 BUTTONS_INSTALL_DIR=$HOME/.local/bin sh
```

| Variable | Default | Description |
| - | - | - |
| `BUTTONS_VERSION` | `latest` | Pin to a specific release tag (e.g. `v0.128.0`). `latest` resolves the newest release via the GitHub API. |
| `BUTTONS_INSTALL_DIR` | `/usr/local/bin` | Directory to install the `buttons` binary. |
| `GITHUB_TOKEN` | *(none)* | GitHub token sent as `Authorization: Bearer`. Required while the repo is private (`contents:read` scope); optional afterward to avoid API rate limits. |

## What the script does

<Steps>
  <Step title="Detect platform">
    The script identifies your OS and architecture with `uname`. OS maps to `darwin` or `linux` (Windows is unsupported and errors out). Architecture maps to `x86_64` (accepting the `amd64` alias) or `arm64` (accepting `aarch64`). The supported targets are `darwin/arm64`, `darwin/x86_64`, `linux/arm64`, and `linux/x86_64`; any other combination exits with an error.
  </Step>

  <Step title="Resolve version">
    If `BUTTONS_VERSION` is `latest` (the default), the script calls the GitHub Releases API to find the newest release tag. Otherwise it uses your pinned tag as-is. Requests send `GITHUB_TOKEN` in the `Authorization` header when set.
  </Step>

  <Step title="Download archive">
    The script looks up the asset IDs for `buttons_<version>_<os>_<arch>.tar.gz` (the leading `v` is stripped to match the goreleaser numeric naming, e.g. `buttons_0.1.0_darwin_arm64.tar.gz`) and the release-wide `checksums.txt`, then downloads both by ID through `/releases/assets/<id>` with `Accept: application/octet-stream`. Going through the API (rather than a direct asset URL) is what lets the download work against a private repo.
  </Step>

  <Step title="Verify SHA256">
    The script reads the expected hash for the archive out of `checksums.txt`, computes the actual SHA256 with `sha256sum` (or `shasum -a 256` as a fallback), and compares them. On any mismatch — or a missing checksum entry — it exits immediately and installs nothing.
  </Step>

  <Step title="Extract and install">
    Extracts only the `buttons` binary from the archive and installs it with `install -m 0755` into `BUTTONS_INSTALL_DIR`. If that directory is not writable it retries with `sudo`; if `sudo` is unavailable it errors and tells you to point `BUTTONS_INSTALL_DIR` at a writable path. Afterward it runs the installed binary's `--version` as a sanity check and warns if the install directory is not on your `$PATH`.
  </Step>
</Steps>

## Pinning a version

For reproducible agent deployments, always pin a version:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh \
  | BUTTONS_VERSION=v0.128.0 sh
```

This prevents unintended upgrades when you rebuild your image or re-provision a machine.

## Custom install directory

To install without `sudo`, point the script at a user-writable directory:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh \
  | BUTTONS_INSTALL_DIR=$HOME/.local/bin sh
```

The script warns if that directory is not on your `$PATH`. Add it so the `buttons` command resolves:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

## GitHub authentication and rate limits

All release metadata and asset downloads go through the GitHub API. While the repository is private, unauthenticated requests return 404, so `GITHUB_TOKEN` (with `contents:read`) is required. Once the repository is public, the token is optional but still useful: the unauthenticated API allows only 60 requests per hour per IP, which CI runners on shared egress IPs can exhaust. Pass a token to raise the limit:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh \
  | GITHUB_TOKEN=$GH_TOKEN sh
```

<Tip>
  In GitHub Actions, `GITHUB_TOKEN` is provided automatically. Pass it directly — just make sure the workflow has `contents: read` permission for this repository: `GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}`.
</Tip>

## Alpine and BusyBox compatibility

The script is plain POSIX `sh` and depends only on a small set of standard utilities: `curl`, `tar`, `uname`, `mktemp`, and one of `sha256sum` or `shasum`. It runs in Alpine, Debian slim, and BusyBox container images without modification.

## Related

* [Installation](/installation) — full install options including Docker and Go
* [Docker](/deployment/docker) — bake the binary into a container image


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.