<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Usage Guide - Rush Shell Documentation</title>
<link rel="stylesheet" href="styles.css">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link
href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Inter:wght@300;400;500;600;700&display=swap"
rel="stylesheet">
</head>
<body>
<div class="layout">
<nav class="sidebar" id="sidebar">
<div class="sidebar-header">
<div class="logo-container">
<div class="logo">🚀</div>
<h2>Rush Shell</h2>
</div>
</div>
<div class="sidebar-nav">
<a href="index.html" class="nav-link">
<span class="nav-icon">🏠</span>
<span>Overview</span>
</a>
<a href="features.html" class="nav-link">
<span class="nav-icon">⚡</span>
<span>Features</span>
</a>
<a href="installation.html" class="nav-link">
<span class="nav-icon">📦</span>
<span>Installation</span>
</a>
<a href="usage.html" class="nav-link active">
<span class="nav-icon">🎯</span>
<span>Usage</span>
</a>
<a href="architecture.html" class="nav-link">
<span class="nav-icon">🏗️</span>
<span>Architecture</span>
</a>
<a href="compliance.html" class="nav-link">
<span class="nav-icon">✅</span>
<span>POSIX Compliance</span>
</a>
<a href="benchmarks.html" class="nav-link">
<span class="nav-icon">📊</span>
<span>Benchmarks</span>
</a>
</div>
<div class="sidebar-footer">
<div class="version-info">
<span class="version">v0.8.0</span>
<span class="status">~96% POSIX Compliant</span>
</div>
<div class="external-links">
<a href="https://github.com/drewwalton19216801/rush-sh" target="_blank" class="external-link">
<span class="nav-icon">🔗</span>
<span>GitHub</span>
</a>
</div>
</div>
</nav>
<main class="main-content">
<button class="mobile-menu-btn" id="mobileMenuBtn">
<span></span>
<span></span>
<span></span>
</button>
<header class="page-header">
<div class="header-content">
<div class="breadcrumb">
<a href="index.html">Rush Shell Documentation</a> → <span>Usage</span>
</div>
<div class="header-actions">
<button class="theme-toggle" id="themeToggle">
<span class="theme-icon">🌙</span>
</button>
<div class="search-container">
<input type="text" class="search-input" placeholder="Search documentation..."
id="searchInput">
<span class="search-icon">🔍</span>
</div>
</div>
</div>
</header>
<div class="page-content">
<div class="usage-hero">
<h1>🎯 Usage Guide</h1>
<p>Complete guide to using Rush Shell in interactive mode, scripts, and command execution</p>
</div>
<section id="execution-modes">
<h2>🚀 Execution Modes</h2>
<div class="modes-grid">
<div class="mode-card">
<div class="mode-header">
<div class="mode-icon">💻</div>
<h3>Interactive Mode</h3>
<span class="mode-badge">Default</span>
</div>
<p>Start Rush in interactive mode for command-line usage with modern prompt</p>
<div class="code-block">
<pre><code>./target/release/rush-sh</code></pre>
</div>
<div class="mode-features">
<ul>
<li>Modern condensed prompt display</li>
<li>Tab completion for commands and files</li>
<li>Command history and line editing</li>
<li>Automatic ~/.rushrc sourcing</li>
</ul>
</div>
</div>
<div class="mode-card">
<div class="mode-header">
<div class="mode-icon">📜</div>
<h3>Script Mode</h3>
<span class="mode-badge">File Execution</span>
</div>
<p>Execute commands from a script file</p>
<div class="code-block">
<pre><code>./target/release/rush-sh script.sh</code></pre>
</div>
<div class="mode-features">
<ul>
<li>Execute multiple commands from file</li>
<li>Full variable and function support</li>
<li>Access to all Rush features</li>
<li>Proper exit code handling</li>
</ul>
</div>
</div>
<div class="mode-card">
<div class="mode-header">
<div class="mode-icon">⚡</div>
<h3>Command Mode</h3>
<span class="mode-badge">Single Command</span>
</div>
<p>Execute a single command string and exit</p>
<div class="code-block">
<pre><code>./target/release/rush-sh -c "echo Hello World"</code></pre>
</div>
<div class="mode-features">
<ul>
<li>Quick command execution</li>
<li>Access to all shell features</li>
<li>Immediate exit after completion</li>
<li>Perfect for scripting and automation</li>
</ul>
</div>
</div>
</div>
</section>
<section id="interactive-usage">
<h2>💻 Interactive Usage</h2>
<div class="interactive-sections">
<div class="interactive-section">
<h3>Basic Commands</h3>
<div class="code-block">
<pre><code>/h/d/p/r/rush-sh $ echo "Hello, Rush!"
Hello, Rush!
/h/d/p/r/rush-sh $ pwd
/home/drew/projects/rush-sh
/h/d/p/r/rush-sh $ ls -la
drwxr-xr-x 12 drew drew 4096 Oct 2 01:00 .</code></pre>
</div>
</div>
<div class="interactive-section">
<h3>Directory Navigation</h3>
<div class="code-block">
<pre><code># Change directory
cd /tmp
# Print working directory
pwd
# Directory stack management
pushd /var
pushd /usr
dirs
popd</code></pre>
</div>
</div>
<div class="interactive-section">
<h3>Tab Completion</h3>
<p>Use Tab for intelligent completion:</p>
<div class="code-block">
<pre><code># Command completion
cd<TAB>
# Shows: cd, env, exit, ...
# File completion
cat f<TAB>
# Completes to: cat file.txt
# Path completion
ls src/m<TAB>
# Completes to: ls src/main/</code></pre>
</div>
</div>
</div>
</section>
<section id="script-usage">
<h2>📜 Script Usage</h2>
<div class="script-sections">
<div class="script-section">
<h3>Basic Script</h3>
<div class="script-example">
<div class="script-header">hello.sh</div>
<div class="code-block">
<pre><code>#!/usr/bin/env rush-sh
echo "Hello, World!"
echo "Current directory: $(pwd)"
echo "User: $USER"</code></pre>
</div>
</div>
<div class="script-execution">
<div class="code-block">
<pre><code>chmod +x hello.sh
./target/release/rush-sh hello.sh</code></pre>
</div>
</div>
</div>
<div class="script-section">
<h3>Script with Source Command</h3>
<p>Use <code>source</code> or <code>.</code> to bypass shebang and execute with Rush:</p>
<div class="code-block">
<pre><code># For scripts with #!/usr/bin/env bash
source script.sh
. script.sh</code></pre>
</div>
</div>
<div class="script-section">
<h3>Complex Script Example</h3>
<div class="script-example">
<div class="script-header">backup.sh</div>
<div class="code-block">
<pre><code>#!/usr/bin/env rush-sh
# Configuration
BACKUP_DIR="/tmp/backup"
SOURCE_DIR="$HOME/Documents"
# Create backup directory
mkdir -p "$BACKUP_DIR"
# Generate timestamp
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Create backup with timestamp
BACKUP_NAME="backup_$TIMESTAMP.tar.gz"
# Create compressed backup
tar -czf "$BACKUP_DIR/$BACKUP_NAME" "$SOURCE_DIR"
# Report success
echo "Backup created: $BACKUP_NAME"
echo "Location: $BACKUP_DIR"
echo "Size: $(du -h "$BACKUP_DIR/$BACKUP_NAME" | cut -f1)"</code></pre>
</div>
</div>
</div>
</div>
</section>
<section id="command-examples">
<h2>💡 Command Examples</h2>
<div class="examples-grid">
<div class="example-category">
<h3>File Operations</h3>
<div class="code-block">
<pre><code># List files with details
ls -la
# Find files by pattern
find . -name "*.rs" -type f
# Count lines in files
wc -l src/*.rs
# Search in files
grep -r "fn main" src/</code></pre>
</div>
</div>
<div class="example-category">
<h3>Text Processing</h3>
<div class="code-block">
<pre><code># Sort and unique
cat file.txt | sort | uniq
# Count words
wc -w document.txt
# Extract columns
cut -d',' -f1 data.csv
# Replace text
sed 's/old/new/g' file.txt</code></pre>
</div>
</div>
<div class="example-category">
<h3>Process Management</h3>
<div class="code-block">
<pre><code># List processes
ps aux
# Monitor resource usage
top
# Kill process by PID
kill -TERM 1234</code></pre>
</div>
</div>
<div class="example-category">
<h3>Network Operations</h3>
<div class="code-block">
<pre><code># Download file
curl -O https://example.com/file.zip
# Check connectivity
ping -c 3 google.com
# DNS lookup
nslookup github.com
# HTTP headers
curl -I https://api.github.com</code></pre>
</div>
</div>
<div class="example-category">
<h3>Archive Management</h3>
<div class="code-block">
<pre><code># Create tar archive
tar -czf archive.tar.gz directory/
# Extract tar archive
tar -xzf archive.tar.gz
# Create zip archive
zip -r archive.zip directory/
# List archive contents
tar -tzf archive.tar.gz</code></pre>
</div>
</div>
<div class="example-category">
<h3>System Information</h3>
<div class="code-block">
<pre><code># System information
uname -a
# Memory usage
free -h
# Disk usage
df -h
# CPU information
lscpu</code></pre>
</div>
</div>
</div>
</section>
<section id="advanced-usage">
<h2>🔥 Advanced Usage</h2>
<div class="advanced-sections">
<div class="advanced-section">
<h3>Complex Pipelines</h3>
<div class="code-block">
<pre><code># Multi-stage processing
find . -name "*.log" -exec wc -l {} \; | \
awk '{sum += $1} END {print "Total lines:", sum}'
# Chained commands
cat file.txt | grep "pattern" | sort | uniq -c</code></pre>
</div>
</div>
<div class="advanced-section">
<h3>Job Control</h3>
<div class="code-block">
<pre><code># Run command in background
sleep 10 &
echo "PID of background job: $!"
# List all jobs
jobs
jobs -l # Show PIDs
jobs -p # Show PIDs only
# Bring job to foreground
fg %1 # By job number
fg %sleep # By command prefix
fg %?eep # By command substring
# Resume job in background
bg %1
# Send signal to job
kill %1 # SIGTERM
kill -9 %2 # SIGKILL
# Wait for job completion
wait %1 # Wait for specific job
wait # Wait for all jobs
# Multiple background jobs
sleep 5 & sleep 10 & sleep 15 &
jobs
wait # Wait for all to complete</code></pre>
</div>
</div>
<div class="advanced-section">
<h3>Signal Handling with trap</h3>
<div class="code-block">
<pre><code># Trap signals
trap 'echo "Interrupted!"; exit' INT
# Custom signal handling
cleanup() {
echo "Cleaning up..."
rm -f temp_*
}
trap cleanup EXIT
# Multiple signals
trap 'echo "Signal received"' INT TERM HUP
# Display current traps
trap
# Reset trap to default
trap - INT</code></pre>
</div>
</div>
<div class="advanced-section">
<h3>Subshells</h3>
<div class="code-block">
<pre><code># Execute commands in subshell
(cd /tmp && ls)
# Current directory unchanged after subshell
# Subshell with variable isolation
(VAR=value; echo "Inside: $VAR")
echo "Outside: $VAR" # VAR not set
# Nested subshells
((echo "Level 2"))
# Subshell with exit code
(exit 42)
echo "Exit code: $?" # 42</code></pre>
</div>
</div>
<div class="advanced-section">
<h3>File Descriptor Operations</h3>
<div class="code-block">
<pre><code># Duplicate file descriptors
exec 3>&1 # Save stdout to FD 3
exec 4<&0 # Save stdin to FD 4
# Redirect to specific FD
echo "Error message" >&2 # Write to stderr
# Close file descriptors
exec 3>&- # Close FD 3
exec 4<&- # Close FD 4
# Open file for read/write
exec 5<>file.txt
echo "data" >&5
exec 5>&-</code></pre>
</div>
</div>
<div class="advanced-section">
<h3>Here-documents</h3>
<div class="code-block">
<pre><code># Multi-line input with expansion
cat << EOF
User: $USER
Home: $HOME
Date: $(date)
EOF
# Here-string (single line)
grep "pattern" <<< "search this text"
wc -w <<< "count these words"
# Here-document without expansion
cat << 'EOF'
Literal $USER
No expansion: $(date)
EOF</code></pre>
</div>
</div>
</div>
</section>
<section id="tips-tricks">
<h2>🎯 Tips and Tricks</h2>
<div class="tips-grid">
<div class="tip-card">
<div class="tip-icon">⚡</div>
<h3>Keyboard Shortcuts</h3>
<ul>
<li><kbd>Ctrl+C</kbd> - Interrupt current command</li>
<li><kbd>Ctrl+D</kbd> - Exit shell (EOF)</li>
<li><kbd>Tab</kbd> - Command/file completion</li>
<li><kbd>↑/↓</kbd> - Navigate command history</li>
</ul>
</div>
<div class="tip-card">
<div class="tip-icon">📁</div>
<h3>Directory Stack</h3>
<ul>
<li><code>pushd <em>dir</em></code> - Push directory to stack</li>
<li><code>popd</code> - Pop directory from stack</li>
<li><code>dirs</code> - Show directory stack</li>
<li>Great for navigating between multiple directories</li>
</ul>
</div>
<div class="tip-card">
<div class="tip-icon">🎨</div>
<h3>Customization</h3>
<ul>
<li><code>set_colors <em>on/off</em></code> - Enable/disable colors</li>
<li><code>set_color_scheme <em>scheme</em></code> - Change color scheme</li>
<li><code>set_condensed <em>on/off</em></code> - Toggle condensed prompt</li>
<li><code>source ~/.rushrc</code> - Load custom configuration</li>
</ul>
</div>
<div class="tip-card">
<div class="tip-icon">🛠️</div>
<h3>Built-in Commands</h3>
<ul>
<li><code>alias</code> / <code>unalias</code> - Manage command aliases</li>
<li><code>export <em>var</em>=<em>value</em></code> - Export variables to environment
</li>
<li><code>unset <em>var</em></code> - Remove variables</li>
<li><code>help</code> - Show available built-in commands</li>
</ul>
</div>
<div class="tip-card">
<div class="tip-icon">🛡️</div>
<h3>Best Practices</h3>
<ul>
<li>Always quote variables: <code>"$variable"</code></li>
<li>Prefer <code>$(command)</code> over backticks for command substitution</li>
<li>Use <code>export</code> to make variables available to child processes</li>
<li>Use descriptive variable names</li>
</ul>
</div>
<div class="tip-card">
<div class="tip-icon">🔧</div>
<h3>Scripting Features</h3>
<ul>
<li><code>source <em>script.sh</em></code> - Execute script in current shell</li>
<li>Full support for <code>$(...)</code> command substitution</li>
<li>Parameter expansion: <code>${VAR:-default}</code></li>
<li>Brace expansion: <code>{1..5}</code> and <code>{a,b,c}</code></li>
</ul>
</div>
</div>
</section>
<div class="section-nav">
<div class="nav-links">
<a href="installation.html" class="nav-button secondary">
<span>← Installation</span>
</a>
<a href="architecture.html" class="nav-button primary">
<span>Architecture Guide</span>
<span class="nav-arrow">→</span>
</a>
</div>
</div>
</div>
</main>
</div>
<script src="script.js"></script>
</body>
</html>