This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Build CLI

Install

macOS 15+ / Linux (Homebrew)

Install Homebrew and setup envs:

brew -v||eval "$(bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"|tee /dev/fd/2|grep '^    [es]')"

brew install buildio/cli/bld;brew trust buildio/cli

macOS (MacPorts)

sudo sh -c 'm=/mac$0/;f=$1-$0.pub;u=https://$1.github.io/cli$m;cd /opt/local/share$m;curl -fsSLO $u$f;cd ../../etc$m;echo $OLDPWD/$f>>pubkeys.conf;echo $u$0.tar>>sources.conf' ports buildio
sudo port sync && sudo port install bld

Windows (Chocolatey)

Install Chocolatey using elevated powershell:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iwr https://community.chocolatey.org/install.ps1 -UseBasicParsing | iex

choco source add --name=buildio --source="https://buildio.github.io/cli/chocolatey/index.json"
choco install bld -y

Windows (Scoop)

Install Scoop using non-elevated powershell:

Set-ExecutionPolicy 4 0 -f;irm get.scoop.sh|iex;scoop install git

scoop bucket add buildio https://github.com/buildio/cli
scoop install bld

Linux (APT)

curl -fsSL https://buildio.github.io/cli/install.sh | sh

Same APT setup without curl | sh:

curl -fsSL https://buildio.github.io/cli/apt/gpg.key | gpg --batch --yes --dearmor | sudo tee /usr/share/keyrings/buildio-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/buildio-archive-keyring.gpg] https://buildio.github.io/cli/apt stable main" | sudo tee /etc/apt/sources.list.d/buildio-cli.list >/dev/null
echo 'Dir::Etc{SourceList sources.list.d/buildio-cli.list;SourceParts /dev/null}#clear APT::Update;'|sudo apt-get -c/dev/fd/0 update --no-list-cleanup
sudo apt-get install -y buildio-archive-keyring bld

Linux (APK)

sudo sh -c 'e=/etc/$1;u=https://$0.github.io/cli/$1;k=$0.rsa.pub;wget -qO $e/keys/$k $u/$k;echo $u>>$e/repositories' buildio apk
sudo apk update&&sudo apk add bld

Linux (pacman)

sudo sh -c 'u=https://$0.github.io/cli/$1;$2 $u/k|$1-key -a -;$1-key --lsign-key $($2 $u/f);printf "[bld]\nServer=$u/$arch\n">>/etc/$1.conf' buildio pacman curl\ -fsSL
sudo pacman -Sy bld

Linux (RPM)

sudo sh -c 'u=https://$0.github.io/cli/rpm;printf "[bld]\nbaseurl=$u/$basearch\ngpgcheck=1\ngpgkey=$u/k\n">>/etc/yum.repos.d/$0-cli.repo' buildio
sudo dnf install -y bld

On older RPM systems (RHEL/CentOS 7, Amazon Linux 2), use yum install -y bld instead of dnf.

Build

Local Development Build

shards build

Release Builds

The repository includes GitHub Actions that build release artifacts before creating the version tag. The Release CLI workflow prepares the release source, invokes the reusable Linux, macOS, and Windows build workflows, waits for every artifact and validation job to succeed, then creates the tag and GitHub release. The platform workflows build the static Linux binaries, Debian packages, the APT repository, the Alpine packages, the APK repositories, the pacman packages, the pacman repositories, the RPM packages, the RPM repositories, precompiled macOS binaries for MacPorts, and the Windows package artifacts. The APT, APK, pacman, RPM, and MacPorts repositories are published to GitHub Pages.

• Purpose: Creates a completely static Linux binary using Alpine Linux for maximum portability
• Use Cases:
  • Provides an easy-to-use binary for Linux users without Crystal dependencies
  • Serves as a dependency for the Build CLI CNB Buildpack
• Trigger: The Release CLI workflow runs from the SDK update dispatch or manual workflow dispatch; the tag is created only after all release artifacts pass validation
• Build Process: Uses Docker with Alpine Linux for the static Linux binary (natively on both amd64 and arm64 runners, so no emulation is needed for compilation), and MacPorts-hosted dependencies on GitHub macOS runners for Darwin binaries that install under /opt/local; Intel binaries request MACOSX_DEPLOYMENT_TARGET=10.7 for Lion and newer, while Apple Silicon binaries target macOS 11.0 and newer
• Output: Releases bld-linux-amd64.zip, bld-linux-arm64.zip, bld-darwin-amd64.tar.gz, bld-darwin-arm64.tar.gz, bld_<version>-1_amd64.deb, bld_<version>-1_arm64.deb, buildio-archive-keyring_<version>-1_all.deb, bld_<version>-r0.apk, bld_<version>-r0_aarch64.apk, bld_<version>-1-x86_64.pkg.tar.zst, bld_<version>-1-x86_64.pkg.tar.zst, bld_<version>-1-aarch64.pkg.tar.zst, bld_<version>-1.x86_64.rpm, and bld_<version>-1.aarch64.rpm package assets; the APT, APK, pacman, and RPM repositories serve both amd64/x86_64 and arm64/aarch64, so the same install steps work on both architectures

To trigger a new release manually:

gh workflow run release.yml

APT publishing needs a stable GPG signing key because users' apt clients trust the repository through /usr/share/keyrings/buildio-archive-keyring.gpg. The workflow bootstraps that key automatically when APT_GPG_PRIVATE_KEY_BASE64 is missing: it generates a repository signing key, uses it for the current publish, and saves APT_GPG_PRIVATE_KEY_BASE64 through the persistent APT_SECRET_BOOTSTRAP_TOKEN secret. The signing key ID is derived from the imported private key on each run, so there is no separate key-id secret. The public key bundle is derived from the signing key by default; set the repository variable APT_GPG_PUBLIC_KEYS_BASE64 only when planned rotation needs an old+new armored public-key bundle. Keeping APT_SECRET_BOOTSTRAP_TOKEN lets the workflow update APT signing secrets during future bootstrap/rotation work without another manual token handoff. To seed it, open GitHub's official fine-grained PAT form with prefilled owner/expiration/permission fields, select only the buildio/cli repository manually, generate the token, paste it into the prompt, and store it with open 'https://github.com/settings/personal-access-tokens/new?name=Build.io+APT+bootstrap&description=Persistent+token+used+by+the+Build+CLI+release+workflow+to+store+and+rotate+APT+signing+secrets&target_name=buildio&expires_in=none&secrets=write' && read -rsp 'Paste fine-grained PAT: ' APT_SECRET_BOOTSTRAP_TOKEN && echo && gh secret set APT_SECRET_BOOTSTRAP_TOKEN --repo buildio/cli --body "$APT_SECRET_BOOTSTRAP_TOKEN". GitHub documents target_name as the resource owner, not as a selected repository, so the repository selection remains manual. The buildio-archive-keyring package owns /usr/share/keyrings/buildio-archive-keyring.gpg, so publish old+new public keys while the old key still signs the repository, let users update, then switch the private-key secret to the new signing key.

APK publishing needs a stable RSA signing key because users' apk clients trust the repository through /etc/apk/keys/buildio.rsa.pub. The workflow bootstraps that key automatically when APK_SIGNING_KEY_BASE64 is missing: it generates a 4096-bit key named buildio.rsa, uses it for the current publish, and saves APK_SIGNING_KEY_BASE64 through the persistent APT_SECRET_BOOTSTRAP_TOKEN secret. The key has no expiry (apk's raw RSA signatures carry no certificate layer), so rotation happens only on compromise. On rotation, keep the old public key in the publish keys so previously published packages keep verifying, and users re-run the same /etc/apk/keys curl from the README.

Pacman publishing needs a stable GPG signing key because users' pacman clients trust the repository through pacman-key (import + local sign of the key fingerprint). The workflow bootstraps that key automatically when PACMAN_GPG_PRIVATE_KEY_BASE64 is missing: it generates a 4096-bit RSA key for "Build.io Pacman Repository", uses it for the current publish, and saves PACMAN_GPG_PRIVATE_KEY_BASE64 through the persistent APT_SECRET_BOOTSTRAP_TOKEN secret. The key is published at pacman/k and its fingerprint at pacman/f, so the install setup can feed both to pacman-key without manual copy-paste.

RPM publishing needs a stable GPG signing key because users' dnf/yum clients verify packages through the repository's gpgcheck and the repository metadata through repo_gpgcheck. The workflow bootstraps that key automatically when RPM_GPG_PRIVATE_KEY_BASE64 is missing (same pattern as the other repository keys, persisted through APT_SECRET_BOOTSTRAP_TOKEN). Packages carry embedded signatures via rpmsign, the repository repodata/repomd.xml carries a detached signature, and the public key is published at rpm/k. The .repo stanza points gpgkey= at it, so dnf imports the key automatically on first install; older yum users import it with rpm --import when prompted.

MacPorts publishing uses a Signify signature because port sync verifies HTTPS ports tree snapshots before extracting them. The macOS workflow bootstraps MACPORTS_SIGNIFY_PRIVATE_KEY_BASE64 and MACPORTS_SIGNIFY_PUBLIC_KEY_BASE64 through the same APT_SECRET_BOOTSTRAP_TOKEN secret when they are missing, publishes macports/ports.tar, signs it as macports/ports.tar.sig, and publishes macports/buildio-ports.pub for users to add to pubkeys.conf. The Portfile installs precompiled bld-darwin-amd64.tar.gz or bld-darwin-arm64.tar.gz release assets; it does not build the CLI from source on user machines. The Intel artifact requests the oldest 64-bit Intel deployment target, macOS 10.7 Lion, and the workflow fails if the produced binary reports a newer minimum target.

The workflow generates the published install.sh from the manual APT setup code block above, so that block is the single source of truth for both install paths.

If the workflow publishes gh-pages but https://buildio.github.io/cli/install.sh returns 404, enable GitHub Pages from the gh-pages branch root:

gh api --method POST repos/buildio/cli/pages -f source[branch]=gh-pages -f source[path]=/

Using a Custom API URL

You can specify a custom API endpoint for the CLI by setting the BUILD_API_URL environment variable. This is useful for development or testing against a local or alternative Build API instance.

The URL should include the scheme (http or https) and the port if necessary.

Example:

To run the CLI against a local server running on http://localhost:3000:

BUILD_API_URL='http://localhost:3000' bld login

When BUILD_API_URL is set, the CLI will direct all API requests to this URL, and it will store a separate entry in your .netrc file for this custom host, ensuring your regular Build credentials are not overwritten.

If BUILD_API_URL is not set, the CLI defaults to https://app.build.io.

Language selection

bld uses BUILD_LOCALE when set, then falls back to LC_ALL, LC_MESSAGES, and LANG. Supported values currently normalize to en or ja; unsupported locales, C, and POSIX fall back to English.

BUILD_LOCALE=ja bld help apps:list

Contributors

• Matthew Chigira - creator and maintainer

License

All rights reserved.