cli

BoringCache CLI Installation Setup

This document describes how to set up the curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" https://install.boringcache.com/install.sh | sh installation method for the BoringCache CLI. The explicit no-cache headers ensure Cloudflare (or any intermediary CDN) revalidates the script on each install.

The installer always verifies every downloaded artifact against SHA256SUMS. On macOS it installs both the universal CLI and the universal Xcode CAS adapter beside it. Archive save and restore run inside the CLI through its Rust tar runtime; no separate tar executable or package-manager setup is required. When cosign 3.1.3 or newer is available, the installer also verifies the signed checksum bundle automatically. If auto mode finds an older or unrecognized cosign, the installer stops and asks for an upgrade instead of silently falling back to checksum-only verification. Set BORINGCACHE_VERIFY_SIGNATURE=0 only when you intend to opt out explicitly.

For fail-closed Sigstore verification, install cosign 3.1.3 or newer first and run:

curl -sSL https://install.boringcache.com/install.sh | BORINGCACHE_VERIFY_SIGNATURE=1 sh

Files Overview

• install.sh - The installation script that users will curl and execute
• install-web/ - Static website files for the installation page
• install-web/index.html - Landing page with installation instructions and manual download links

Setup Instructions

1. Domain Setup

You’ll need to configure install.boringcache.com/install.sh to serve the installation script. Here are a few options:

Option A: GitHub Pages (Recommended)

1. Create a new repository boringcache/install
2. Upload install.sh and install-web/ contents to the repository
3. Enable GitHub Pages to serve from the main branch
4. Configure custom domain install.boringcache.com/install.sh in repository settings
5. Add CNAME record in DNS: install.boringcache.com/install.sh → boringcache.github.io

Option B: Cloudflare Pages

1. Connect the CLI repository to Cloudflare Pages
2. Set build command to copy installation files to output directory
3. Configure custom domain install.boringcache.com/install.sh

Option C: Simple Static Hosting

Use any static file hosting service (Netlify, Vercel, etc.) to serve:

• Root path / serves install.sh with Content-Type: text/plain
• Path /web serves install-web/index.html

2. Web Server Configuration

The installation script should be served with proper headers:

# Nginx example
location = / {
    add_header Content-Type text/plain;
    try_files /install.sh =404;
}

location /web/ {
    try_files $uri $uri/ /install-web/index.html;
}

3. DNS Configuration

Add these DNS records:

install.boringcache.com/install.sh  CNAME  your-hosting-provider.com

4. SSL Certificate

Ensure HTTPS is enabled since users will be downloading and executing scripts.

Testing the Installation

Test the script URL:

curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
  https://install.boringcache.com/install.sh

Should return the installation script content.

Test the installation:

curl -sSL -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
  https://install.boringcache.com/install.sh | sh

Should detect platform, download appropriate binary, and install it.

Test manual download links:

# Should redirect to latest release
curl -I https://github.com/boringcache/cli/releases/latest/download/boringcache-linux-amd64

Platform Support

The installation script supports:

• Linux: AMD64, ARM64
• macOS: Apple Silicon and Intel through universal binaries
• Windows: AMD64 (experimental, manual download recommended)

Binary Names

The GitHub release workflow creates these binaries:

• boringcache-linux-amd64
• boringcache-linux-arm64
• boringcache-linux-musl-amd64
• boringcache-linux-musl-arm64
• boringcache-macos-universal
• libboringcache_xcode_cas-macos-universal.dylib
• boringcache-windows-amd64.exe
• boringcache-windows-arm64.exe
• SHA256SUMS
• SHA256SUMS.bundle

Installation Locations

The script installs the CLI to the first writable location. On macOS it also installs libboringcache_xcode_cas.dylib in that same directory so boringcache xcode works without a separate plugin setup:

1. /usr/local/bin (with sudo if needed)
2. $HOME/.local/bin
3. $HOME/bin

Security Considerations

• Downloads over HTTPS only
• Provides warning about piping curl to shell
• Verifies the downloaded binary against SHA256SUMS
• Automatically verifies SHA256SUMS.bundle with Sigstore when cosign 3.1.3 or newer is available; an installed older or unrecognized verifier stops auto mode, and BORINGCACHE_VERIFY_SIGNATURE=1 remains fail-closed
• Accepts checksum signatures only from the monorepo CLI release workflow on a semantic-version tag or the checksum-repair workflow on main
• Shows installation path and PATH information
• Includes verification step after installation

Maintenance

• Update REPO variable in install.sh if repository moves
• Update download links in index.html if repository moves
• Monitor GitHub API rate limits for release fetching

Future Enhancements

• Support for installing specific versions
• Package manager installations (brew, apt, etc.)
• Windows MSI installer
• Auto-update mechanism in the CLI itself

This site is open source. Improve this page.