The BerryBox CLI

The CLI needs Node.js 24.22.2 or newer on macOS or Linux. The release archive includes its JavaScript dependencies. You do not need the BerryBox source checkout or a public npm package.

Install

Run in a new directory so the download does not replace existing project files:

mkdir berrybox-install &&
cd berrybox-install &&
curl --fail --location --remote-name https://docs.berrybox.io/downloads/berrybox-cli.tgz &&
curl --fail --location --remote-name https://docs.berrybox.io/downloads/berrybox-cli.tgz.sha256 &&
shasum -a 256 --check berrybox-cli.tgz.sha256 &&
npm install --global --prefix "$HOME/.local" --offline --ignore-scripts ./berrybox-cli.tgz &&
export PATH="$HOME/.local/bin:$PATH" &&
berrybox --version

Continue only if the checksum check reports OK. Add the PATH line to your shell configuration to keep the command available in future terminals. To pin a release or automate installation, read /downloads/latest.json for versioned archive and checksum paths, SHA-256, byte size and required Node version.

Log in without putting a key in chat

Create a key in Settings → API keys with teams:read and ci:read. Set the API origin and enter the key through this hidden Bash/Zsh prompt:

export BERRYBOX_API_URL="https://berrybox.io"
{
  printf 'Agent key (hidden): '
  read -rs BERRYBOX_LOGIN_TOKEN
  printf '\n'
  printf '%s' "$BERRYBOX_LOGIN_TOKEN" | berrybox login --token-stdin
  unset BERRYBOX_LOGIN_TOKEN
}
berrybox overview

The CLI stores credentials in ~/.config/berrybox/credentials.json with owner-only permissions. berrybox logout removes the local copy; revoke the key in the dashboard to disable every copy. Do not pass a key as a command-line argument or commit it in a config file.

Useful commands

berrybox help
berrybox pricing
berrybox runners
berrybox jobs --search api
berrybox job --job-id JOB_UUID
berrybox wait --job-id JOB_UUID --timeout-seconds 300
berrybox logs --job-id JOB_UUID --search error --limit 50
berrybox wallet
berrybox budget

wallet and budget need billing:read plus an allowed team role. Other commands may need their matching scope; berrybox help lists the available operations.

Output and errors are JSON. wait uses bounded server waits and can wait up to 30 minutes in one invocation. Log search is literal text over published GitHub logs, with a maximum of 200 returned lines and a bounded log download. It is not an AI diagnosis.

Write access

Mutations require a matching write scope, a permitted role and explicit confirmation (--yes). An agent cannot gain permissions by setting the flag. Review the operation before allowing it; GitHub authorization and payments still finish in your browser.

For key creation and rotation, use the CLI's --output-token FILE option to save the one-time token privately. Those operations are excluded from MCP so the secret is not returned into an AI conversation.

Workflow migration · MCP setup · Key scopes