Overview Global options are specified before the command (e.g., single-turn, multi-turn) and apply to all CLI operations.
cbl [global-options] < command > [command-options]
API Configuration Circuit Breaker Labs API Key Circuit Breaker Labs API key for authentication with the CBL evaluation service. Environment Variable: CBL_API_KEY# Set via environment variable (recommended) export CBL_API_KEY = "your-api-key-here" cbl single-turn ... # Or pass directly (not recommended for security) cbl --cbl-api-key "your-api-key-here" single-turn ...
Keep your API key secure. Never commit it to version control. Use environment variables or secure secret management.
Circuit Breaker Labs API Base URL --cbl-api-base-url
string
default: "https://api.circuitbreakerlabs.com"
Base URL for the Circuit Breaker Labs API endpoint. Typically only changed for custom deployments or testing. Environment Variable: CBL_API_BASE_URL# Use default production endpoint (most common) cbl single-turn ... # Use custom endpoint export CBL_API_BASE_URL = "https://custom.api.example.com" cbl single-turn ... # Or pass directly cbl --cbl-api-base-url "https://custom.api.example.com" single-turn ...
The default value points to Circuit Breaker Labs’ production API. Only change this if you’re using a custom deployment or testing environment.
Logging Options Log Level Sets the logging verbosity level. Available Levels:
error - Only critical errorswarn - Warnings and errorsinfo - General information (default)debug - Detailed debugging informationtrace - Very detailed trace information # Default info logging cbl single-turn ... # Debug logging for troubleshooting cbl --log-level debug single-turn ... # Minimal error-only logging cbl --log-level error single-turn ...
Use debug or trace level when troubleshooting issues or reporting bugs.
Log Mode Enable log mode to disable the interactive TUI and output logs directly to stdout. # Default: Interactive TUI cbl single-turn ... # Log mode: Plain text output cbl --log-mode single-turn ... # Useful for CI/CD pipelines cbl --log-mode --log-level debug single-turn ... > output.log
Use Cases:
CI/CD pipelines
Automated scripts
Log file generation
When running in non-interactive environments
When --log-mode is enabled, the TUI (Terminal User Interface) is disabled and all output goes to stdout, making it suitable for automation.
Output Configuration Output File Specify a custom path for evaluation results. If not provided, results are saved with an auto-generated timestamp. # Auto-generated filename (default) cbl single-turn ... # Creates: evaluation_results_2026-03-08_14-30-45.json # Custom filename cbl --output-file results.json single-turn ... # Custom path and filename cbl --output-file ./reports/eval-2026-03-08.json single-turn ...
Default Format: evaluation_results_YYYY-MM-DD_HH-MM-SS.jsonUse descriptive filenames that include dates, model names, or test identifiers for better organization: --output-file "eval-gpt4o-$( date +%Y%m%d).json"
Add custom HTTP headers to provider requests. Can be specified multiple times for multiple headers. Format: Key:Value# Single custom header cbl --add-header "X-Custom-Header:value" single-turn ... # Multiple custom headers cbl --add-header "X-API-Version:v2" \ --add-header "X-Request-ID:abc123" \ single-turn ... # Authentication header (if needed for custom provider) cbl --add-header "Authorization:Bearer token123" \ single-turn ...
Use Cases:
Custom authentication for providers
Request tracking headers
API version specification
Custom routing headers
Custom headers are sent to the provider API (OpenAI, Ollama, or custom), not to Circuit Breaker Labs API.
Complete Examples Basic Setup with Environment Variables # Set API keys once export CBL_API_KEY = "your-cbl-api-key" export OPENAI_API_KEY = "your-openai-api-key" # Run evaluations without repeating credentials cbl single-turn --threshold 0.5 --variations 2 --maximum-iteration-layers 2 openai --model gpt-4o
Production Evaluation with Custom Output cbl --output-file "prod-eval-$( date +%Y%m%d).json" \ --log-level info \ single-turn \ --threshold 0.3 \ --variations 3 \ --maximum-iteration-layers 2 \ openai \ --model gpt-4o
CI/CD Pipeline Configuration #!/bin/bash # evaluation.sh - CI/CD script cbl --log-mode \ --log-level info \ --output-file "ci-evaluation-${ CI_BUILD_ID }.json" \ single-turn \ --threshold 0.4 \ --variations 2 \ --maximum-iteration-layers 2 \ openai \ --model $MODEL_NAME 2>&1 | tee evaluation.log
Debug Mode with Verbose Logging cbl --log-mode \ --log-level debug \ --output-file debug-results.json \ single-turn \ --threshold 0.5 \ --variations 2 \ --maximum-iteration-layers 2 \ openai \ --model gpt-4o 2>&1 | tee debug.log
cbl --cbl-api-base-url "https://custom.cbllabs.internal" \ --add-header "X-Request-ID:$( uuidgen )" \ --add-header "X-Environment:staging" \ --output-file staging-eval.json \ single-turn \ --threshold 0.5 \ --variations 2 \ --maximum-iteration-layers 2 \ custom \ --url https://internal.api.example.com/chat \ --script ./custom-provider.rhai
Multi-Turn with Complete Configuration export CBL_API_KEY = "your-api-key" export OPENAI_API_KEY = "your-openai-key" cbl --log-level info \ --output-file "multi-turn-eval.json" \ multi-turn \ --threshold 0.5 \ --max-turns 8 \ --test-types user_persona,semantic_chunks \ openai \ --model gpt-4o \ --temperature 0.9
Environment Variables Summary All global options can be set via environment variables:
CLI Option Environment Variable Required Default --cbl-api-keyCBL_API_KEYYes None --cbl-api-base-urlCBL_API_BASE_URLNo https://api.circuitbreakerlabs.com--log-levelN/A No info--log-modeN/A No false--output-fileN/A No Auto-generated --add-headerN/A No None
Setting Environment Variables Bash/Zsh
Fish Shell
PowerShell
Docker Compose
# Add to ~/.bashrc or ~/.zshrc export CBL_API_KEY = "your-api-key" export CBL_API_BASE_URL = "https://api.circuitbreakerlabs.com" export OPENAI_API_KEY = "your-openai-key"
Best Practices Security Never commit API keys to version control. Use environment variables or secret management systems.
# Good: Use environment variables export CBL_API_KEY = "your-key" cbl single-turn ... # Bad: Pass keys in command line (visible in history) cbl --cbl-api-key "your-key" single-turn ...
Logging Strategy Development: Use --log-level debug with --log-mode for detailed troubleshooting.Production: Use --log-level info without --log-mode for the interactive TUI.CI/CD: Use --log-mode with appropriate log level and redirect to files.
Output Organization # Create organized output structure mkdir -p ./evaluations/ $( date +%Y-%m ) cbl --output-file "./evaluations/$( date +%Y-%m)/eval-$( date +%Y%m%d-%H%M%S).json" \ single-turn ...
Single-Turn Single-turn command reference
Multi-Turn Multi-turn command reference
Commands Overview Overview of all commands