View on GitHub

Installation

Get started with BotBox in just a few minutes.

Prerequisites

  • Python (3.11+): Install Python — required to run the bots BotBox generates
  • Go (v1.24+): Install Go — only required if you install BotBox with go install
  • (Optional) Doppler: For advanced environment variable management (Doppler)

1. Install BotBox

Pick whichever method fits your setup. All three install the same botbox binary.

Homebrew (macOS/Linux)

sh
brew install choice404/tap/botbox

Prebuilt binary

Every release ships archives for Linux, macOS, and Windows on amd64 and arm64. Grab the archive for your platform from the releases page, extract it, and move botbox somewhere on your PATH.

sh
tar -xzf botbox_Linux_x86_64.tar.gz
sudo mv botbox /usr/local/bin/

Go install

This requires Go on your system and builds BotBox from source.

sh
go install github.com/choice404/botbox/v2@latest
📝 NOTE
botbox update updates in place with go install, so it only works if Go is installed. If you installed with Homebrew, update with brew upgrade botbox instead. If you installed a prebuilt binary, download the new one from the releases page.

2. Install Go (only for go install)

If you don't have Go installed, follow the official instructions.

💡 TIP
You can use webi for a quick Go install:
sh
# Linux/macOS
curl -sS https://webi.sh/golang | sh; source ~/.config/envman/PATH.env

# Windows (PowerShell)
curl.exe https://webi.ms/golang | powershell

3. Verify Installation

sh
botbox --version

You should see the current BotBox version printed.

4. (Optional) Install Doppler

If you want to use Doppler for environment management:

sh
# macOS
brew install dopplerhq/cli/doppler

# Linux
curl -sLf --retry 3 --retry-delay 2 https://cli.doppler.com/install.sh | sh

# Windows
choco install doppler

5. First Run

Run any BotBox command to generate your global config:

sh
botbox

This will create a config file at:

  • Linux/macOS: $HOME/.config/botbox/config.json
  • Windows: %USERPROFILE%\.config\botbox\config.json

6. Upgrading

If you installed with go install:

sh
botbox update

If you installed with Homebrew:

sh
brew upgrade botbox

7. Troubleshooting

If you see a "command not found" error, make sure the directory holding the binary is in your PATH.

  • On Linux/macOS with go install: add export PATH="$PATH:$(go env GOPATH)/bin" to your shell profile.
  • On Windows with go install: add %USERPROFILE%\go\bin to your system PATH.

If botbox update warns that the updated binary is in a different location than the one you are running, you have two copies of BotBox installed. Check your PATH order or remove the older copy.

Next Steps