Skip to main content
Circuit Breaker Labs CLI is distributed as pre-built binaries for all major platforms. This guide will help you install cbl and get it configured with the necessary API keys.

​
Prerequisites

Before installing, you’ll need:
  1. Circuit Breaker Labs API Key - Required to run evaluations
  2. Model Provider API Key - Depending on which provider you use:
    • OpenAI API key for OpenAI models
    • Ollama installed locally for Ollama models
    • Custom endpoint credentials for custom providers
Circuit Breaker Labs CLI requires API access. If you don’t have an API key yet, contact [email protected] to get access.

​
Installation Methods

Pre-built executables for Linux, macOS, and Windows are available with each release. Visit the releases page to download the latest version.
1

Download the Binary

Go to the Circuit Breaker Labs CLI releases page and download the appropriate binary for your platform:
  • Linux: cbl-linux-x86_64.tar.gz
  • macOS (Intel): cbl-macos-x86_64.tar.gz
  • macOS (Apple Silicon): cbl-macos-aarch64.tar.gz
  • Windows: cbl-windows-x86_64.zip
2

Extract and Install

# Extract the archive
tar -xzf cbl-*.tar.gz

# Move to a directory in your PATH
sudo mv cbl /usr/local/bin/

# Make it executable (if needed)
chmod +x /usr/local/bin/cbl
3

Verify Installation

Confirm that cbl is installed correctly:
cbl help
You should see the Circuit Breaker Labs CLI help output with available commands and options.

​
Shell-Specific Installation (Linux/macOS)

The releases page also provides shell-specific installation commands for quick setup: 
# Copy the bash installation command from the releases page
curl -fsSL https://github.com/circuitbreakerlabs/cli/releases/download/v0.1.3/install.sh | bash
The installation scripts automatically detect your platform and download the correct binary.

​
Configuration

​
Setting Up API Keys

Circuit Breaker Labs CLI requires environment variables for authentication. Set these in your shell profile:
1

Circuit Breaker Labs API Key

Export your Circuit Breaker Labs API key:
export CBL_API_KEY="your_circuit_breaker_labs_api_key_here"
You can also pass this as a command-line argument: --cbl-api-key YOUR_KEY
2

Provider API Keys

Set the appropriate API key for your model provider:
export OPENAI_API_KEY="your_openai_api_key_here"
3

Make Environment Variables Persistent

Add the export commands to your shell profile so they persist across sessions:
# For bash: add to ~/.bashrc or ~/.bash_profile
echo 'export CBL_API_KEY="your_key_here"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="your_key_here"' >> ~/.bashrc

# For zsh: add to ~/.zshrc
echo 'export CBL_API_KEY="your_key_here"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="your_key_here"' >> ~/.zshrc

# For fish: use set -Ux
set -Ux CBL_API_KEY "your_key_here"
set -Ux OPENAI_API_KEY "your_key_here"
Never commit API keys to version control. Use environment variables or secret management tools.

​
Optional Configuration

You can customize the Circuit Breaker Labs API endpoint if needed: 
export CBL_API_BASE_URL="https://api.circuitbreakerlabs.ai/v1"
Most users don’t need to set CBL_API_BASE_URL - the default value works for standard installations.

​
Verification

Verify your installation and configuration:
1

Check CLI Version

cbl --version
Should output: circuit-breaker-labs 0.1.3 (or current version)
2

View Available Commands

cbl help
You should see:
  • Available evaluation types: single-turn, multi-turn
  • Global options: --cbl-api-key, --output-file, --log-mode
  • Usage examples
3

Check Provider Options

# Check OpenAI provider options
cbl single-turn openai --help

# Check Ollama provider options
cbl single-turn ollama --help

# Check custom provider options
cbl single-turn custom --help

​
Platform-Specific Notes

​
Linux

  • Ensure the binary has execute permissions: chmod +x cbl
  • Add to PATH by placing in /usr/local/bin or ~/.local/bin
  • Tested on Ubuntu 20.04+, Debian 11+, Fedora 35+, and Arch Linux

​
macOS

  • Apple Silicon (M1/M2/M3): Use the aarch64 binary
  • Intel Macs: Use the x86_64 binary
  • You may need to allow the binary in System Preferences → Security & Privacy if you see a security warning
  • Alternatively, remove the quarantine attribute: xattr -d com.apple.quarantine /usr/local/bin/cbl

​
Windows

  • Extract the ZIP file to a permanent location (e.g., C:\Program Files\cbl\)
  • Add the directory to your PATH environment variable
  • Run from PowerShell, Command Prompt, or Windows Terminal
  • Git Bash and WSL are also supported

​
Troubleshooting

The cbl binary is not in your PATH. Either:
  1. Move it to a directory in your PATH: sudo mv cbl /usr/local/bin/
  2. Add the directory containing cbl to your PATH
  3. Run it with the full path: /path/to/cbl
The binary doesn’t have execute permissions. Fix with:
chmod +x /path/to/cbl
You need to export your Circuit Breaker Labs API key:
export CBL_API_KEY="your_key_here"
Or pass it as a flag: cbl --cbl-api-key YOUR_KEY ...
macOS Gatekeeper is blocking the binary. Options:
  1. Go to System Preferences → Security & Privacy and click “Open Anyway”
  2. Remove the quarantine attribute: xattr -d com.apple.quarantine /usr/local/bin/cbl
Export your OpenAI API key:
export OPENAI_API_KEY="sk-..."
Or pass it directly: cbl single-turn openai --api-key sk-... --model gpt-4

​
Getting API Access

To get your Circuit Breaker Labs API key:

Request API Access

Click here to email the Circuit Breaker Labs team and request API access. Include information about your use case and the models you plan to evaluate.

​
Next Steps

Now that you have cbl installed and configured:

Quickstart Guide

Run your first evaluation in minutes

View on GitHub

Explore the source code and examples
Need help? Contact [email protected]

Build docs developers (and LLMs) love

Get started for freeTalk to us