Configuration

The BuildBear CLI uses two configuration files: a global user config for your API key, and an optional per-project config that stores your sandbox connection details.

Global user config

Location: ~/.config/buildbear/config.json

Permissions: 0600 (user read/write only — set automatically by the CLI)

Format:

{
  "apiKey": "your-api-key-here"
}

This file is created by buildbear auth setup or buildbear auth login and deleted by buildbear auth logout.

You should never edit this file manually — use the auth commands instead.

Project config (.buildbear.json)

Location: .buildbear.json in the current working directory

Created by buildbear init. Stores your sandbox connection details so that commands which accept an optional [rpcUrl] argument don't require one.

Format:

{
  "rpcUrl": "https://rpc.buildbear.io/<sandbox-id>",
  "network": "Ethereum",
  "chainId": 1,
  "forkChainId": 1,
  "explorerUrl": "https://explorer.buildbear.io/<sandbox-id>"
}

Fields:

Commands that read this file: buildbear status, buildbear faucet native, buildbear faucet erc20, buildbear snapshot take, buildbear snapshot revert, buildbear rpc.

Environment variables

Setting BUILDBEAR_API_KEY is the recommended approach for CI/CD pipelines:

# GitHub Actions example
env:
  BUILDBEAR_API_KEY: ${{ secrets.BUILDBEAR_API_KEY }}

Authentication priority

When a command needs to authenticate, the CLI checks in this order:

1. BUILDBEAR_API_KEY environment variable
2. ~/.config/buildbear/config.json

If neither is present, the command exits with:

Not authenticated. Run 'buildbear auth setup' to get started, or set BUILDBEAR_API_KEY env var.

RPC URL resolution priority

When a command accepts an optional [rpcUrl] argument, it resolves the URL in this order:

1. Explicit rpcUrl argument passed on the command line
2. rpcUrl field in .buildbear.json in the current directory

If neither is found, the command exits with:

No RPC URL provided and no .buildbear.json found in current directory.
Run buildbear init or pass an RPC URL.

Gitignore recommendations

.buildbear.json contains a personal sandbox URL. Whether to commit it depends on your team's workflow:

• Commit it if your team shares a single sandbox
• Gitignore it if each developer uses their own sandbox

To ignore it:

echo ".buildbear.json" >> .gitignore