Global Options

Global command-line options that apply to all Circuit Breaker Labs CLI commands

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

--cbl-api-key · string · required

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

--log-level · enum · default: "info"

Sets the logging verbosity level.

Available Levels:

• error - Only critical errors
• warn - Warnings and errors
• info - General information (default)
• debug - Detailed debugging information
• trace - 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

--log-mode · boolean · default: "false"

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

--output-file · string

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.json

Use descriptive filenames that include dates, model names, or test identifiers for better organization:

--output-file "eval-gpt4o-$(date +%Y%m%d).json"

Custom Headers

Add Header

--add-header · string

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

Custom Endpoint with Headers

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-key	CBL_API_KEY	Yes	None
--cbl-api-base-url	CBL_API_BASE_URL	No	https://api.circuitbreakerlabs.com
--log-level	N/A	No	info
--log-mode	N/A	No	false
--output-file	N/A	No	Auto-generated
--add-header	N/A	No	None

Setting Environment Variables

Bash/Zsh

# 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 ...

Related Documentation

Single-Turn

Single-turn command reference

Multi-Turn

Multi-turn command reference

Commands Overview

Overview of all commands