Installation and updates

Install a versioned release without repository access, verify its checksum, and pin it in automation.

Homebrew on macOS

Homebrew is the recommended path on macOS. It installs the current version and upgrades it with everything else on your machine.

brew install vulk-corp/tap/bworlds
bworlds --version

Homebrew verifies the release checksum before it installs. The tap is a public repository that carries the formula only.

Upgrade with the rest of your tools:

brew upgrade

A package install cannot write into your home directory, so it installs no skills. Run bworlds agent setup afterwards, which The skills explains.

Installer script

Use the script on Linux, in automation, and on macOS without Homebrew. Run it in one line:

curl -fsSL https://docs.bworlds.co/install.sh | sh

If your organization requires you to inspect it first, download it, read it, then run it:

curl -fsSLO https://docs.bworlds.co/install.sh
less install.sh
sh install.sh

It installs the newest published version. The installer downloads one archive and that release's checksums.txt, verifies SHA-256 before extraction, and installs the bworlds executable. It supports:

Operating system	Architecture	Archive suffix
macOS	Apple silicon	`darwin-arm64`
macOS	Intel	`darwin-amd64`
Linux	x86-64	`linux-amd64`

It installs into $HOME/.local/bin by default and tells you when that directory is not on your PATH. Set BWORLDS_INSTALL_DIR to choose another directory.

In a terminal, the installer then runs bworlds agent setup, and bworlds auth login unless you are already signed in. When its output goes to a file or a pipe, as in automation or a coding agent, it prints those commands instead of running them. Set BWORLDS_NO_SETUP=1 to get the printed commands in a terminal too.

The skills

Seven skills teach a coding agent how to operate a Build:

Skill	What it does
`bworlds-cli`	The command contract, exit codes and safety rules every other skill loads
`bworlds-brief`	Free orientation on a Build you have just been given access to
`bworlds-triage`	Trace one production error to the code path that produces it
`bworlds-fix`	Take one Finding to a change your own coding agent wrote, then have BWorlds recheck it
`bworlds-audit`	Audit a Build end to end
`bworlds-check`	A recurring health check
`bworlds-guardrails`	Print a Build's guardrails in the form your own agent reads

The executable carries all seven, so one command installs them and needs nothing else:

bworlds agent setup

It finds the coding agents on your machine and keeps one copy of each skill at $HOME/.agents/skills/<name>/SKILL.md, the shared path many agents read directly. Each agent that reads a directory of its own gets a link to that copy, such as $HOME/.claude/skills/<name> for Claude Code. It recognizes Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, opencode and Windsurf, and counts an agent as present when the directory it keeps in your home directory exists.

Because the skills travel inside the executable, they describe the commands the version you installed exposes. Run the command again after an upgrade to move every agent to the new text.

Flag	Effect
`--dry-run`	Report the actions and write nothing
`--agent <id>`	Install for one agent instead of every agent found
`--scope project`	Install into the working directory instead of your home directory. Detection still reads your home directory, so name an agent with `--agent` to install for one you use only in that project
`--force`	Reinstall, replacing a skill copy another installer left behind

bworlds agent status reports what is already installed and changes nothing. A skill reads as current when it matches the text your executable carries, and as outdated when another version installed it. Both commands take --json.

The cross-agent installer

For an agent bworlds agent setup does not know, the same skills are published here and the cross-agent installer takes them:

npx skills add https://docs.bworlds.co/bworlds-cli-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-brief-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-triage-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-fix-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-audit-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-check-SKILL.md -g
npx skills add https://docs.bworlds.co/bworlds-guardrails-SKILL.md -g

It lands in the same places, needs Node, and always takes the newest published skill rather than the one matching your executable. Drop -g to install into the repository you are working in.

Without either, save each published skill, bworlds-cli, bworlds-brief, bworlds-triage, bworlds-fix, bworlds-audit, bworlds-check and bworlds-guardrails, as $HOME/.agents/skills/<name>/SKILL.md, then link those directories into your agent's own skills directory.

Pin a version

Homebrew, and the script with no BWORLDS_VERSION, both install the newest published version. Automation should pin one instead, so a release cannot change what a run executes:

BWORLDS_VERSION=<version> sh install.sh

The current version appears at the top of the CLI command reference and in the cliVersion field of /command-reference.json. bworlds --version reports the one you installed.

Minimum supported version

The API serves a minimum version and refuses every request from a binary below it. A refused command exits 11 and prints the floor it misses together with the command that clears it. Nothing else fails first, so a retired flag never reads as a problem with the command you typed.

GET /api/cli/config publishes the current floor as minimum_cli_version, and that route answers whatever version asks for it. A binary built from source reports a commit rather than a version and is never refused.

Only versions below the floor are refused. A supported version that is not the newest keeps working and pays nothing for the check.

Update

brew upgrade bworlds moves a Homebrew install to the newest published version, and running the script again without BWORLDS_VERSION does the same. With a pinned version, run it again with a newer one; it replaces the executable. Your sign-in survives either path. Run bworlds agent setup afterwards to move the skills to the new version; the script already does it when it runs in a terminal. Review the generated reference for the new version before changing the pinned version in automation.