🎯 Usage Guide

Complete guide to using Rush Shell in interactive mode, scripts, and command execution

🚀 Execution Modes

💻

Interactive Mode

Default

Start Rush in interactive mode for command-line usage with modern prompt

./target/release/rush-sh

Modern condensed prompt display
Tab completion for commands and files
Command history and line editing
Automatic ~/.rushrc sourcing

📜

Script Mode

File Execution

Execute commands from a script file

./target/release/rush-sh script.sh

Execute multiple commands from file
Full variable and function support
Access to all Rush features
Proper exit code handling

⚡

Command Mode

Single Command

Execute a single command string and exit

./target/release/rush-sh -c "echo Hello World"

Quick command execution
Access to all shell features
Immediate exit after completion
Perfect for scripting and automation

💻 Interactive Usage

Basic Commands

/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 .

Directory Navigation

# Change directory
cd /tmp

# Print working directory
pwd

# Directory stack management
pushd /var
pushd /usr
dirs
popd

Tab Completion

Use Tab for intelligent completion:

# Command completion
cd
# Shows: cd, env, exit, ...

# File completion
cat f
# Completes to: cat file.txt

# Path completion
ls src/m
# Completes to: ls src/main/

📜 Script Usage

Basic Script

hello.sh

#!/usr/bin/env rush-sh
echo "Hello, World!"
echo "Current directory: $(pwd)"
echo "User: $USER"

chmod +x hello.sh
./target/release/rush-sh hello.sh

Script with Source Command

Use source or . to bypass shebang and execute with Rush:

# For scripts with #!/usr/bin/env bash
source script.sh
. script.sh

Complex Script Example

backup.sh

#!/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)"

💡 Command Examples

File Operations

# 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/

Text Processing

# 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

Process Management

# List processes
ps aux

# Monitor resource usage
top

# Kill process by PID
kill -TERM 1234

Network Operations

# 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

Archive Management

# 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

System Information

# System information
uname -a

# Memory usage
free -h

# Disk usage
df -h

# CPU information
lscpu

🔥 Advanced Usage

Complex Pipelines

# 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

Job Control

# 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

Signal Handling with trap

# 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

Subshells

# 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

File Descriptor Operations

# 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>&-

Here-documents

# 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

🎯 Tips and Tricks

⚡

Keyboard Shortcuts

Ctrl+C - Interrupt current command
Ctrl+D - Exit shell (EOF)
Tab - Command/file completion
↑/↓ - Navigate command history

📁

Directory Stack

pushd dir - Push directory to stack
popd - Pop directory from stack
dirs - Show directory stack
Great for navigating between multiple directories

🎨

Customization

set_colors on/off - Enable/disable colors
set_color_scheme scheme - Change color scheme
set_condensed on/off - Toggle condensed prompt
source ~/.rushrc - Load custom configuration

🛠️

Built-in Commands

alias / unalias - Manage command aliases
export var=value - Export variables to environment
unset var - Remove variables
help - Show available built-in commands

🛡️

Best Practices

Always quote variables: "$variable"
Prefer $(command) over backticks for command substitution
Use export to make variables available to child processes
Use descriptive variable names

🔧

Scripting Features

source script.sh - Execute script in current shell
Full support for $(...) command substitution
Parameter expansion: ${VAR:-default}
Brace expansion: {1..5} and {a,b,c}

← Installation Architecture Guide →