Ruby Butler 🎩

A distinguished Ruby environment manager with the refined approach of a gentleman's butler

⚠️ Prototype Status: This is a prototype—not recommended for serious usage yet, even though the author has been using it daily for job work for some time. See IDEAS.md for potential future enhancements. Please share your ideas via issues.

🎭 Development Fun: The butler-themed language and refined terminology are just for entertainment during development and will be updated before any real production release, if any.

Ruby Butler selects Ruby, prepares dependencies, and runs commands without changing your shell environment. Bundler is the default package backend. An opt-in native backend resolves and installs gems while retaining RubyGems and Bundler at application runtime. On Linux and macOS, Butler can also install missing Ruby runtimes.

Hiring Your Butler (Installation)

Download the latest production binary for your platform from releases and add to PATH:

Linux

curl -L https://github.com/RubyElders/ruby-butler/releases/latest/download/rb-linux -o ~/.local/bin/rb && chmod +x ~/.local/bin/rb

macOS (Apple Silicon)

curl -L https://github.com/RubyElders/ruby-butler/releases/latest/download/rb-macos -o ~/.local/bin/rb && chmod +x ~/.local/bin/rb

Windows

Invoke-WebRequest -Uri "https://github.com/RubyElders/ruby-butler/releases/latest/download/rb-windows.exe" -OutFile "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\rb.exe"

Quick Start

Install Ruby on Linux or macOS, then check available installations (by default in ~/.rubies):

# Install the latest matching prebuilt CRuby
rb install ruby 4.0

# Survey your distinguished Ruby installations
rb info runtime

Ruby Butler composes gem and bundle commands with environmental intelligence:

• In Ruby environments: Respects your Ruby environment selection
• In Bundler environments: Respects Gemfile and applies bundle exec automatically
• Ruby Detection: Honors .ruby-version files and Gemfile ruby requirements

# Execute with latest Ruby (default behavior)
rb x ruby -v

# Execute with specific Ruby version
rb -r 3.4.5 x ruby -v

# Create a new Rails project with distinguished precision
rb x gem exec rails new butler-test
cd butler-test

# Synchronize bundler environment (handles bundle install)
rb sync

# Launch Rails console in the prepared environment  
rb x rails c

# Execute any Ruby command with proper environmental preparation
rb x gem list
rb x rake test

Why Butler?

Unlike traditional Ruby managers that alter your shell environment, Ruby Butler employs a service-oriented approach:

• No Environment Pollution: Your shell remains pristine—Butler prepares environments per-execution
• Automatic Bundler Integration: Detects Gemfile projects and applies bundle exec intelligently
• Intelligent Composition: Combines Ruby installations, gem environments, and bundler projects seamlessly
• Graceful Error Handling: Provides sophisticated guidance when commands or environments are missing

This approach mirrors how a distinguished butler operates: preparing everything behind the scenes, serving with precision, then disappearing without a trace.

Installation Requirements

Ruby Butler expects Ruby installations in ~/.rubies/ (the standard location for ruby-install and similar tools). It discovers and composes:

• Ruby Runtimes: Installed via rb install ruby on Linux/macOS, or an external installer on any supported platform
• Gem Environments: User gem directories (~/.gem/ruby/X.Y.Z/)
• Bundler Projects: Detected automatically via Gemfile presence

Missing Ruby runtimes are installed automatically for sync, exec, and run on Linux/macOS. Disable this with --no-auto-install-ruby, RB_AUTO_INSTALL_RUBY=false, or auto-install-ruby = false in your global config. Native gem compilation still requires a compiler and the gem's system libraries.

Commands

• rb exec / rb x - Execute commands within meticulously prepared environments
• rb sync / rb s - Synchronize bundler environments (also auto-triggered when needed)
• rb run / rb r - Execute project scripts defined in rbproject.toml
• rb new - Create a minimal rbproject.toml in the current directory
• rb info runtime - Survey your Ruby estate with elegant presentation
• rb info env - Display current environment composition
• rb info project - Show resolved project settings
• rb info config - Display merged configuration with sources
• rb install ruby [version] - Install a matching prebuilt CRuby on Linux/macOS
• rb export-gemfile - Export Gemfile declarations to stdout as TOML (or --format kdl)
• rb version - Display version information
• rb shell-integration bash - Generate bash completions (eval "$(rb shell-integration bash)")

Configuration

• rb.toml - Global configuration file (in ~/.config/rb/ or ~/.rb.toml)
• rbproject.toml or gem.toml - Project-level script definitions and metadata

To use native dependency preparation by default, add to your global rb.toml:

package-backend = "native"

Use package-backend "native" in KDL. RB_PACKAGE_BACKEND=native selects it for a shell session; --package-backend native selects it for one command. Set it to bundler to switch back. Inspect effective settings with rb info config. See the 0.4.0 changelog for new features, defaults, and limitations.

Development

This is a concept demonstration showcasing a heavily opinionated approach to Ruby environment management.

Building

cargo build --release

Testing

Rust Unit & Integration Tests:

cargo test

Shell Integration Tests (shellspec):

./shellspec

PowerShell Integration Tests (Pester):

# Setup once
pwsh tests/Setup.ps1

# Run repeatedly  
Invoke-Pester tests/

Architecture

• rb-core: Environment detection, composition, and orchestration
• rb-cli: Distinguished command-line interface with refined messaging
• rb-tests: Sophisticated testing utilities for realistic environment simulation

Ruby Butler is built with Rust for cross-platform reliability and employs a environment-agnostic design—no shell modifications required.

If you're curious about what Butler does under the hood, add -v or -V to see the distinguished orchestration in action.

Release Process

To create a new release with cross-platform binaries:

1. Update version in root Cargo.toml (workspace version), refresh Cargo.lock, and update the Ruby helper versions under gems/
2. Update CHANGELOG.md with release notes
3. Create and push tag:

   git tag v1.0.0
   git push --tags

The release workflow automatically:

• Builds binaries for Linux, macOS (Apple Silicon), and Windows (both release and debug)
• Creates GitHub release with binaries attached
• Embeds git information in version output (rb version)

Released binaries include version traceability:

• Tagged builds: Ruby Butler v1.0.0
• Development builds: Ruby Butler v0.1.0 (c5156b1) [debug build] [modified]

---

Distinguished Ruby development deserves distinguished tooling.