Docs - Common Workflows - BuildBear Labs

End-to-end examples showing how to combine BuildBear CLI commands for typical development and testing scenarios.

1. First-time setup

# 1. Install the CLI
npm install -g buildbear

# 2. Authenticate with your API key
buildbear auth setup

# 3. Verify authentication
buildbear auth status

2. Initialize a project sandbox

Run once per project. Creates a .buildbear.json for your project directory.

cd my-project/

# Interactive wizard: pick a network, fork block, and prefund addresses
buildbear init

# Verify the sandbox is live
buildbear status

After this, all other commands can be run from the same directory without specifying a URL.

3. Fund a test wallet and run tests

# Fund a test account with 100 ETH
buildbear faucet native --address 0xYourTestWallet --amount 100

# Fund a USDC balance (Ethereum USDC contract address)
buildbear faucet erc20 \
  --token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
  --address 0xYourTestWallet \
  --amount 10000

# Run your test suite
npm test

4. Snapshot-based testing (repeatable runs)

Take a snapshot before your tests so you can revert to a clean state after every run.

#!/usr/bin/env bash
set -e

RPC=$(cat .buildbear.json | jq -r '.rpcUrl')

# Fund your test wallet
buildbear faucet native --address 0xYourTestWallet --amount 100

# Take a baseline snapshot
SNAPSHOT=$(buildbear snapshot take $RPC --json | jq -r '.snapshotId')
echo "Snapshot: $SNAPSHOT"

# Run tests
npm test

# Revert to clean state for next run
buildbear snapshot revert $RPC --snapshot "$SNAPSHOT"
echo "Reverted to snapshot $SNAPSHOT"

5. CI/CD pipeline

Use environment variables for authentication and create a fresh sandbox per pipeline run.

# GitHub Actions example
name: Test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      BUILDBEAR_API_KEY: ${{ secrets.BUILDBEAR_API_KEY }}

    steps:
      - uses: actions/checkout@v4

      - name: Install CLI
        run: npm install -g buildbear

      - name: Create sandbox
        id: sandbox
        run: |
          OUTPUT=$(buildbear sandbox create --network 1 --json)
          echo "rpc_url=$(echo $OUTPUT | jq -r '.rpcUrl')" >> $GITHUB_OUTPUT

      - name: Fund test wallet
        run: |
          buildbear faucet native \
            ${{ steps.sandbox.outputs.rpc_url }} \
            --address ${{ vars.TEST_WALLET_ADDRESS }} \
            --amount 100

      - name: Run tests
        run: npm test
        env:
          RPC_URL: ${{ steps.sandbox.outputs.rpc_url }}

      - name: Cleanup sandbox
        if: always()
        run: buildbear sandbox delete ${{ steps.sandbox.outputs.rpc_url }} --quiet

6. Deploy and verify a contract

# Deploy with Foundry (targeting the sandbox)
forge create src/MyContract.sol:MyContract \
  --rpc-url https://rpc.buildbear.io/my-sandbox-id \
  --private-key 0xYourTestPrivateKey

# Verify the deployed contract
buildbear contract verify https://rpc.buildbear.io/my-sandbox-id \
  --address 0xDeployedContractAddress \
  --type etherscan

# Fetch the ABI to confirm verification
buildbear contract abi https://rpc.buildbear.io/my-sandbox-id \
  --address 0xDeployedContractAddress

7. Inspect chain state with raw RPC

# Check current block
buildbear rpc --method eth_blockNumber | jq '.result'

# Check a balance (result is in wei, hex-encoded)
buildbear rpc --method eth_getBalance \
  --params '["0xYourAddress", "latest"]' | jq '.result'

# Get chain ID
buildbear rpc --method eth_chainId | jq '.result'

8. Clean up after development

# List all your sandboxes
buildbear sandbox list

# Delete a sandbox you no longer need
buildbear sandbox delete https://rpc.buildbear.io/old-sandbox-id

# Log out when done
buildbear auth logout

Common Workflows

On this page