Automatically initialize and instrument with braintrust exec

[delner]

Purpose

This PR introduces a new braintrust exec CLI command that enables auto-instrumentation of Ruby applications without any code changes. This is the third and most frictionless approach to enabling Braintrust tracing, complementing the existing Braintrust.init and require "braintrust/setup" methods.

The key benefit is that users can instrument existing applications simply by prefixing their run command with braintrust exec --.

Usage Examples

Before you begin: the braintrust gem must be installed on your system to make the CLI available in your PATH.

Basic Usage

# Run a Ruby script with auto-instrumentation
braintrust exec -- ruby app.rb

# Run a Rails server with auto-instrumentation
braintrust exec -- rails server

# Run with bundler
braintrust exec -- bundle exec rails server

Filtering Integrations

# Only instrument OpenAI and Anthropic
braintrust exec --only openai,anthropic -- ruby app.rb

# Instrument everything except RubyLLM
braintrust exec --except ruby_llm -- ruby app.rb

Help and Version

braintrust --help
braintrust --version

Comparison: Three Approaches to Auto-Instrumentation

Approach	Code Changes	Best For
Braintrust.init	Add init call	Customized control
require "braintrust/setup"	Add require (or Gemfile)	Rails or Bundler-enabled Ruby applications
braintrust exec -- cmd	None	When you can't easily change the Ruby application source code or dependencies

---

NOTE: Using braintrust exec requires the braintrust gem be installed onto your system (if you want zero-code changes to an application). This means there are inherent limitations for compatibility, as the system-installed version of the braintrust gem could potentially have conflicts with your Ruby application dependencies.

Using this CLI approach is for when you can't easily add the braintrust gem directly to your application. We recommend using require 'braintrust/setup' in combination with Bundler in your Ruby application whenever possible to maximize compatibility.

---

Environment Variables

Variable	Description
BRAINTRUST_API_KEY	Required for tracing
BRAINTRUST_INSTRUMENT_ONLY	Comma-separated whitelist (set by --only)
BRAINTRUST_INSTRUMENT_EXCEPT	Comma-separated blacklist (set by --except)

Architectural Overview

How It Works

The CLI uses Ruby's RUBYOPT environment variable to inject -rbraintrust/setup before the target application runs:

braintrust exec -- ruby app.rb
        │
        ├─► Sets RUBYOPT="-rbraintrust/setup"
        │
        └─► Kernel.exec("ruby", "app.rb")
                │
                └─► Ruby automatically loads braintrust/setup
                        │
                        ├─► Calls Braintrust.init
                        └─► Calls Contrib::Setup.run! (patches LLM libraries)

CLI Implementation Details

The CLI module in exe/braintrust:

• Parses --only and --except flags for filtering integrations
• Handles the -- separator to distinguish CLI args from command args
• Sets BRAINTRUST_INSTRUMENT_ONLY/BRAINTRUST_INSTRUMENT_EXCEPT env vars for filtering
• Provides graceful error handling for ENOENT (command not found), EACCES, and ENOEXEC
• Returns appropriate exit codes (127 for not found, 126 for permission errors)

Files Added

File	Description
exe/braintrust	CLI executable with argument parsing, option handling, and exec logic
examples/setup/exec.rb	Full example demonstrating all supported LLM libraries
examples/setup/exec_minimal.rb	Minimal working example
examples/setup/README.md	Documentation comparing all three setup approaches