Ruby CLI

Ruby CLI cheatsheet — run scripts, one-liners, gems, irb REPL. ruby script.rb, ruby -e 'puts 42', gem install rails, irb. Ruby command-line reference with examples.

6 min read

What it is

A command-line interface for running Ruby code, scripts, and managing gems.

Installation

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install ruby-full

Linux (Fedora)

sudo dnf install ruby

macOS

Ruby is typically pre-installed. You can check with ruby --version. If you need a different version, use a version manager like rbenv or RVM.

Using rbenv (recommended):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install rbenv
brew install rbenv ruby-build

# Add rbenv to your shell (add to ~/.zshrc or ~/.bash_profile)
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc # or ~/.bash_profile
source ~/.zshrc # or source ~/.bash_profile

# Install a Ruby version
rbenv install 3.2.2 # Replace 3.2.2 with your desired version

# Set the global Ruby version
rbenv global 3.2.2

Windows

Download and install Ruby from the official RubyInstaller website: https://rubyinstaller.org/

Core Concepts

Gems: Ruby packages that provide additional functionality. Managed by the gem command.
IRB (Interactive Ruby): A command-line interactive shell for running Ruby code snippets.
Bundler: A gem for managing application dependencies (gems). While not strictly part of the core ruby CLI, it’s essential for most Ruby projects.

Commands / Usage

Running Ruby Code

Execute a script:
```
ruby my_script.rb
```
Runs the Ruby code contained in my_script.rb.
Execute code from stdin:
```
echo "puts 'Hello, Ruby!'" | ruby
```
Pipes the string "puts 'Hello, Ruby!'" to the ruby interpreter, which executes it.
Execute a single line of code:
```
ruby -e "puts 2 + 2"
```
Executes the Ruby code provided as a string to the -e flag.

Run a script with arguments:

# my_script.rb
puts "First arg: #{ARGV[0]}"
puts "Second arg: #{ARGV[1]}"

# Terminal
ruby my_script.rb apple banana

Passes apple and banana as command-line arguments to the script, accessible via the ARGV array.

Interactive Ruby (IRB)

Start IRB:
```
irb
```
Opens an interactive Ruby console where you can type and execute Ruby code line by line.
Start IRB with specific options (e.g., line editing):
```
irb -r readline
```
Loads the readline library for better line editing capabilities in IRB.

Gem Management (`gem` command)

Install a gem:
```
gem install rails
```
Installs the specified gem and its dependencies.
Install a specific version of a gem:
```
gem install rails -v 7.0.4
```
Installs version 7.0.4 of the rails gem.
List installed gems:
```
gem list
```
Shows all gems currently installed in the environment.
List gems matching a pattern:
```
gem list json
```
Lists all installed gems whose names contain "json".
Uninstall a gem:
```
gem uninstall rails
```
Removes the specified gem from your system.
Uninstall a specific version of a gem:
```
gem uninstall rails -v 7.0.4
```
Removes only version 7.0.4 of the rails gem.
Update a gem:
```
gem update rails
```
Updates the rails gem to the latest available version.
Update all gems:
```
gem update
```
Updates all installed gems to their latest available versions.
Search for gems:
```
gem search httparty
```
Searches RubyGems.org for gems matching the query "httparty".
Show gem information:
```
gem info rails
```
Displays details about the rails gem, including its version, homepage, and description.
Specify gem source:
```
gem install cocoapods --source https://gems.cocoapods.org/
```
Installs the cocoapods gem, explicitly using https://gems.cocoapods.org/ as the source.

Ruby Interpreter Options

Verbose output:
```
ruby -v my_script.rb
```
Prints the Ruby version to standard error before running the script.
Enable warnings:
```
ruby -w my_script.rb
```
Turns on warnings for potential style problems or dangerous constructs.
Enable even more warnings:
```
ruby -w -w my_script.rb
# or
ruby -Wall my_script.rb
```
Enables even more verbose warnings.
Load a library:
```
ruby -r json -e "puts JSON.parse('[1, 2, 3]').inspect"
```
Loads the json library before executing the code with -e.
Specify include path:
```
ruby -I ./lib my_script.rb
```
Adds the ./lib directory to the list of paths Ruby searches for required files (require).
Disable method cache:
```
ruby -F my_script.rb
```
Disables the method cache, which can be useful for debugging.
Disable class cache:
```
ruby -f my_script.rb
```
Disables the class cache, also for debugging purposes.
Set environment variable:
```
ruby -E UTF-8 my_script.rb
```
Sets the default external encoding to UTF-8. Can also be US-ASCII, ASCII-8BIT, etc.
Set internal encoding:
```
ruby -I UTF-8 my_script.rb
```
Sets the default internal encoding to UTF-8.
Specify script encoding:
```
ruby -x my_script.rb
```
Treats the script as having a magic comment (e.g., # encoding: utf-8) to determine its encoding.
Debug mode:
```
ruby -d my_script.rb
```
Enables debug output from the Ruby interpreter.
Profile script execution:
```
ruby -pg my_script.rb
```
Runs the script and prints profiling information after execution.
Profile script execution (with line numbers):
```
ruby -pc my_script.rb
```
Runs the script and prints profiling information with line numbers after execution.
Print to stderr:
```
ruby -s my_script.rb --flag --other=value
```
Enables script modification by command line flags. If --flag is present, the global variable $flag will be true. If --other=value is present, $other will be value.

Common Patterns

Run a Ruby one-liner to process text:
```
echo "hello world" | ruby -ne 'puts $_.upcase'
```
Reads input line by line (-n), converts each line ($_) to uppercase, and prints it.
Quickly test a Ruby snippet:
```
echo "puts Time.now" | ruby
```
Executes the puts Time.now command instantly.
Install a specific gem version for a one-off task:
```
gem install json -v 2.6.1
ruby -r json -e 'puts JSON.generate({a: 1})'
```
Installs a specific version of json, then uses it in a one-liner.
Use Bundler to run a script within a project’s gem context:
```
bundle exec ruby path/to/your/script.rb
```
Ensures the script runs with the gems specified in the project’s Gemfile.lock.
Run IRB with a specific gem loaded:
```
irb -r some_gem
```
Starts an IRB session with some_gem already required.

Gotchas

Global vs. Local Gems: The gem install command installs gems globally for the current Ruby version. For project-specific dependencies, Bundler (bundle install, bundle exec) is the standard and highly recommended approach.
Multiple Ruby Versions: If you have multiple Ruby versions installed (e.g., via rbenv or RVM), ensure you are running the ruby and gem commands associated with the desired version. rbenv and RVM help manage this.
require path: When using require 'some_file', Ruby searches for some_file.rb (or .so, .dll, etc.) in specific directories, including the current directory and paths specified by ruby -I. It does not automatically search subdirectories unless explicitly configured.
ARGV is an Array: Command-line arguments passed to a script are available in the global ARGV array. Remember that ARGV[0] is the first argument, ARGV[1] is the second, and so on.
Encoding Issues: Be mindful of file and string encodings, especially when dealing with non-ASCII characters. Use magic comments (# encoding: utf-8) or ruby -E flags if necessary.