rsh

The Ruby SHell

Why?

<img src="img/rsh-logo.jpg" align="left" width="150" height="150">Ruby is my goto language (pun kinda intended). I want full control over my tools and I like challenges that I can tinker with late at night. This is an incomplete project continually being improved. Feel free to add suggestions or code.

Design principles

Simple. One file. Minimum external requirements.

Installation

Clone this repo and drop rsh into your preferred bin directory. Drop .rshrc into your home directory and edit as you see fit.

Or simply gem install ruby-shell.

Screencast

Features

Key Features

Aliases (Nicks)

rsh uses "nicks" for aliases - both simple command shortcuts and powerful parametrized templates:

# Simple aliases
:nick la = ls -la
:nick gs = git status

# Parametrized nicks (templates with {{placeholders}})
:nick gp = git push origin {{branch}}
gp branch=main              # Executes: git push origin main

:nick deploy = ssh {{user}}@{{host}} 'systemctl restart {{app}}'
deploy user=admin host=prod app=api

# List and manage
:nick                       # List all nicks
:nick -la                   # Delete a nick

Intelligence & Learning

Completion Learning: Shell learns which TAB completions you use and ranks them higher
Smart Suggestions: "Did you mean...?" for typos
Auto-correct: Optional auto-fix with confirmation
Command Analytics: :stats shows usage patterns and performance

Productivity

Command Recording: :record start name → run commands → :record stop → :replay name
Sessions: Save/load entire shell state with bookmarks, history, and functions
Bookmarks: Tag directories and jump instantly
Multi-line Editing: Press Ctrl-G to edit in $EDITOR
Shell Scripts: Full bash support for for/while/if loops

Extensibility

Plugin System: Add custom commands, completions, and hooks
Ruby Functions: Define callable functions - :defun hello(name) = puts "Hello, #{name}!"
Validation Rules: :validate rm -rf / = block prevents dangerous commands
6 Color Themes: solarized, dracula, gruvbox, nord, monokai, default

Integrations

AI Support: @ for questions, @@ for command suggestions (Ollama or OpenAI)
RTFM: Launch file manager with r
fzf: Fuzzy finder with f
XRPN: Calculator with = expression

Tab Completion

Smart context-aware completion for git, apt, docker, systemctl, cargo, npm, gem
Command switches from --help
Option values (--format=json, --level=debug)
Learns your patterns and adapts

Core Shell

Syntax highlighting for nicks, commands, paths, bookmarks
History with search, edit, and repeat (!, !!, !-2, !5:7)
Job control (background jobs, suspend, resume)
Config file (.rshrc) updates on exit
All colors themeable

Quick Start

# Install
gem install ruby-shell

# Run
rsh

# Create an alias
:nick ll = ls -l
ll

# Create parametrized alias
:nick gp = git push origin {{branch}}
gp branch=main

# Get help
:help
:info

# See version and changelog
:version

Latest Features (v3.4)

Define Ruby functions as shell commands: :defun 'weather(*args) = system("curl -s wttr.in/#{args[0] || \"oslo\"}")'
Call like any shell command: weather london
Full Ruby power: Access to Ruby stdlib, file operations, JSON parsing, web requests, etc.
Function management: :defun to list, :defun -name to remove
Syntax highlighting: Ruby functions highlighted in bold

Advanced Shell Features

Job Control: Background jobs (command &), job suspension (Ctrl-Z), process management
Job Management: :jobs, :fg [id], :bg [id] commands
Command Substitution: $(date) and backtick support
Variable Expansion: $HOME, $USER, $? (exit status)
Conditional Execution: cmd1 && cmd2 || cmd3
Brace Expansion: {a,b,c} expands to a b c
Login Shell Support: Proper signal handling and profile loading

Special functions/integrations:

Use r to launch rtfm (https://github.com/isene/RTFM) - if you have it installed
Use f to launch fzf (https://github.com/junegunn/fzf) - if you have it installed
Use = followed by xrpn commands separated by commas (https://github.com/isene/xrpn)
Use : followed by a Ruby expression to access the whole world of Ruby

Special commands:

:nick ll = ls -l to make a command alias (ll) point to a command (ls -l)
:gnick h = /home/me to make a general alias (h) point to something (/home/me)
:nick lists all command nicks, :gnick lists general nicks
:nick -name delete a command nick, :gnick -name delete a general nick
:history will list the command history, while :rmhistory will delete the history
:rehash rebuilds the executable cache (useful after installing new commands)
:jobs will list background jobs, :fg [job_id] brings jobs to foreground, :bg [job_id] resumes stopped jobs
:defun func(args) = code defines Ruby functions callable as shell commands (persistent!)
:defun lists all user-defined functions, :defun -func removes functions
:stats shows command execution statistics, :stats --graph for visual charts, :stats --clear to reset
:bm name or :bookmark name bookmark current directory, :bm name path #tags with tags
:bm lists all bookmarks, just type bookmark name to jump (e.g., work)
:bm -name delete bookmark, :bm ?tag search by tag, :bm --stats show statistics
:save_session name saves named session, :load_session name loads session
:list_sessions shows all saved sessions, :rmsession name or :rmsession * deletes
:theme name applies color scheme, :config manages settings, :env manages environment
:plugins lists plugins, :plugins disable name disables, :plugins reload reloads
:calc expression inline calculator with Ruby Math library
:info shows introduction and feature overview
:version Shows the rsh version number and the last published gem file version
:help will display a compact command reference in two columns

Background jobs:

Use command & to run commands in background
Use :jobs to list active background jobs
Use :fg or :fg job_id to bring jobs to foreground
Use Ctrl-Z to suspend running jobs, :bg job_id to resume them

AI Configuration

The AI features work out of the box with Ollama for local AI processing. To set up:

Local AI (Recommended)

Install Ollama: curl -fsSL https://ollama.com/install.sh | sh
Pull a model: ollama pull llama3.2
That's it! Use @ What is the capital of France? or @@ list files by size

External AI (OpenAI)

Add to your .rshrc:

@aimodel = "gpt-4"
@aikey = "your-api-key-here"

Moving around

While you cd around to different directories, you can see the last 10 directories visited via the command :dirs or the convenient shortcut #. Entering the number in the list (like 6 and ENTER) will jump you to that directory. Entering - will jump you back to the previous dir (equivalent of 1. Entering ~ will get you to your home dir. If you want to bookmark a special directory, you can do that via a general nick like this: :gnick x = /path/to/a/dir/ - this would bookmark the directory to the single letter x.

Nicks

Nicks are powerful aliases that can be simple command shortcuts or complex parametrized templates.

Simple Nicks

:nick ls = ls --color        # Simple alias
:nick la = ls -la            # Another shortcut
:nick                        # List all nicks
:nick -la                    # Delete a nick

Parametrized Nicks (NEW in v3.3!)

Create templates with {{placeholder}} parameters:

# Git shortcuts with branch parameter
:nick gp = git push origin {{branch}}
gp branch=main               # Executes: git push origin main
gp branch=develop            # Executes: git push origin develop

# Deployment with multiple parameters
:nick deploy = ssh {{user}}@{{host}} 'cd {{path}} && git pull'
deploy user=admin host=prod path=/var/www
# Executes: ssh admin@prod 'cd /var/www && git pull'

# Backup with source and destination
:nick backup = rsync -av {{src}} {{dest}}
backup src=/data dest=/backup
# Executes: rsync -av /data /backup

How it works:

Define nick with {{param}} placeholders
Use with key=value syntax
Parameters auto-expand and get stripped from final command
Works with any number of parameters

General Nicks (gnicks)

Substitute anywhere on command line (not just commands):

:gnick h = /home/user        # Directory shortcut
:gnick                       # List all gnicks
:gnick -h                    # Delete a gnick

Multi-line Command Editing (v3.3.0+)

Press Ctrl-G to edit the current command in your $EDITOR:

# Start typing a complex command
for i in {1..10}

# Press Ctrl-G
# Your editor opens with the command
# Add more lines:
for i in {1..10}
  echo "Processing: $i"
  sleep 1
done

# Save and quit
# Command appears on command line (converted to single-line with ;)
# Press ENTER to execute

Perfect for:

Complex shell scripts
Long commands with many options
Multi-line constructs (for, while, if)
Commands you want to review/edit carefully

Tab completion

You can tab complete almost anything. Hitting TAB will try to complete in this priority: nicks, gnicks, commands, dirs/files. Special completions:

ls -<TAB> lists command switches from --help with descriptions
:st<TAB> completes colon commands (:stats, et

Rsh

Install / Use

README

rsh