Installing the WBSP CLIs

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

There are three binaries:

wbsp is self-contained and safe to distribute. It reads the .env beside your app's wbsp.yaml for app config, and — once you run wbsp login — caches a platform session token at ~/.config/wbsp/token and installs git/docker credential helpers for the platform's hosts (this is what lets git push, docker push, and wbsp deploy work without pasted keys — see credential-less-deploy.md). It never needs or stores AWS / cloud credentials; wbsp logout clears the session.

For application creators — install wbsp

You do not need access to the WBSP source repository. Install wbsp with the one-line script:

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

The script detects your OS/architecture, downloads the matching wbsp, 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

Upgrade later by re-running the same command — it always fetches the latest wbsp (pin a specific one with WBSP_VERSION).

Verify:

wbsp --version

macOS Gatekeeper: binaries fetched via curl 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.

wbsp 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 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@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, 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 destinations — 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 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.
4. Upload of the public wbsp 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