# The BerryBox CLI (/docs/agents/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 [#install]

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

```sh
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`](/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 [#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:

```sh
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 [#useful-commands]

```sh
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 [#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](/docs/ci-runners/migration) · [MCP setup](/docs/agents/mcp) · [Key scopes](/docs/teams-and-billing/management-keys)