Installing the WBSP CLIs

How to install the WBSP command-line tools on macOS or Linux.

There are three binaries:

wbsp-app is self-contained and safe to distribute: it only ever reads the .env beside your app's wbsp.yaml — never platform or cloud credentials.

For application creators — install wbsp-app

You do not need access to the WBSP source repository.

Option A — Homebrew (macOS & Linux)

brew install worlds-biggest-software-project/wbsp/wbsp-app

# upgrade later with:
brew upgrade wbsp-app

Option B — install script

curl -fsSL https://get.wbsp.ai/install.sh | bash

The script detects your OS/architecture, downloads the matching wbsp-app, verifies its SHA-256 checksum, and installs it to /usr/local/bin (or ~/.local/bin if that isn't writable). Useful overrides:

# pin a version
curl -fsSL https://get.wbsp.ai/install.sh | WBSP_VERSION=v0.1.0 bash
# choose the install directory
curl -fsSL https://get.wbsp.ai/install.sh | WBSP_INSTALL_DIR="$HOME/bin" bash

Verify:

wbsp-app --version

macOS Gatekeeper: binaries fetched via curl/Homebrew are not quarantined, so they run without the "unidentified developer" prompt. If you ever download one through a browser, clear the flag with xattr -d com.apple.quarantine ./wbsp-app.

wbsp-app shells out to Docker (and Docker Compose v2) for local builds, so install Docker as well. pg_dump is only needed if you use wbsp-app dump-data.

For platform operators — install the full set

Operators have access to the private wbsp-platform repo and get all three binaries.

Option A — go install (needs Go 1.26+ and repo credentials)

export GOPRIVATE=github.com/worlds-biggest-software-project/*
go install github.com/worlds-biggest-software-project/wbsp-platform/cmd/wbsp-app@latest
go install github.com/worlds-biggest-software-project/wbsp-platform/cmd/wbsp-platform@latest
go install github.com/worlds-biggest-software-project/wbsp-platform/cmd/wbsp-api@latest

Binaries land in $(go env GOBIN) (or $(go env GOPATH)/bin) — make sure it's on your PATH.

Option B — download from the GitHub Release

Grab the archives for your OS/arch from the latest release, extract, and move them onto your PATH. Each release publishes checksums.txt.

Option C — build from source

git clone https://github.com/worlds-biggest-software-project/wbsp-platform
cd wbsp-platform
make build      # -> bin/wbsp-app, bin/wbsp-platform, bin/wbsp-api
make install    # or install them onto your PATH via `go install`

Operator tooling additionally requires the AWS CLI v2, Terraform 1.5+, and kubectl for AWS targets — cluster access is set up by your platform operator.

Cutting a release (maintainers)

Releases are produced by GoReleaser and driven by a git tag.

# dry run — builds everything into dist/, publishes nothing
make snapshot

# real release: push a tag; GitHub Actions runs `goreleaser release` + publishes the
# public wbsp-app subset to the CDN (.github/workflows/release.yml)
git tag v0.1.0
git push origin v0.1.0

A tag triggers:

1. Cross-compiled builds of all three CLIs (darwin/linux × amd64/arm64).
2. A GitHub Release (private) with the full set + checksums.txt — for operators.
3. An updated Homebrew tap (homebrew-wbsp) for wbsp-app.
4. Upload of the public wbsp-app subset + install.sh + latest.txt to the download CDN (S3 + CloudFront) — for clients.

One-time infrastructure (the public download host) lives in deploy/downloads/ in the repository. After terraform apply there, set the release workflow's repository variables/secrets from its outputs: WBSP_PUBLIC_BUCKET, WBSP_PUBLIC_BASE_URL, AWS_RELEASE_ROLE_ARN, AWS_REGION, plus HOMEBREW_TAP_TOKEN (a PAT that can push to the public homebrew-wbsp repo).

To release from a workstation instead of CI:

export WBSP_PUBLIC_BASE_URL=https://get.wbsp.ai
export WBSP_PUBLIC_BUCKET=<bucket-from-terraform>
export GITHUB_TOKEN=<pat-for-homebrew-tap>
make release        # goreleaser release --clean, then scripts/publish-public.sh