Installation

Installation Guide

Complete guide to installing MAINFRAME on your system.

---

Table of Contents

• Requirements
• Quick Install
• Installation Methods
  • User Installation
  • System-Wide Installation
  • Project-Local Installation
  • Git Submodule
  • Docker
• Shell Configuration
• Verifying Installation
• Updating
• Uninstalling
• Troubleshooting

---

Requirements

Required

Requirement	Version	Check Command
Bash	4.0+	bash --version
Git	Any	git --version

Recommended

Requirement	Version	Benefit
Bash	5.0+	Better performance, more features
OpenSSL	Any	Required for HTTPS in http.sh

Platform Support

Platform	Status	Notes
Linux	✅ Full Support	All distributions
macOS	✅ Full Support	Requires Homebrew bash (system bash is 3.x)
WSL/Windows	✅ Full Support	WSL1 and WSL2
FreeBSD	✅ Full Support	Requires bash from ports
Alpine	✅ Full Support	Requires bash package

---

Quick Install

Get MAINFRAME running in 30 seconds:

# 1. Clone MAINFRAME
git clone https://github.com/gtwatts/mainframe.git ~/.mainframe

# 2. Add to your shell profile
echo 'export MAINFRAME_ROOT="$HOME/.mainframe"' >> ~/.bashrc
echo 'source "$MAINFRAME_ROOT/lib/common.sh"' >> ~/.bashrc

# 3. Reload and verify
source ~/.bashrc
mainframe version

Expected output:

MAINFRAME v5.0
2,000+ functions | 77 libraries | Pure Bash

---

Installation Methods

User Installation (Recommended)

Best for personal use on a single machine.

# Clone to home directory
git clone https://github.com/gtwatts/mainframe.git ~/.mainframe

# Add to shell profile
cat >> ~/.bashrc << 'EOF'
# MAINFRAME - AI-Native Bash Runtime
export MAINFRAME_ROOT="$HOME/.mainframe"
source "$MAINFRAME_ROOT/lib/common.sh"
EOF

# Reload shell
source ~/.bashrc

For Zsh users:

# Add to ~/.zshrc instead
cat >> ~/.zshrc << 'EOF'
# MAINFRAME - AI-Native Bash Runtime
export MAINFRAME_ROOT="$HOME/.mainframe"
source "$MAINFRAME_ROOT/lib/common.sh"
EOF

source ~/.zshrc

System-Wide Installation

Best for shared systems or servers where all users need MAINFRAME.

# Clone to /opt (requires sudo)
sudo git clone https://github.com/gtwatts/mainframe.git /opt/mainframe

# Create system profile script
sudo tee /etc/profile.d/mainframe.sh > /dev/null << 'EOF'
# MAINFRAME - AI-Native Bash Runtime
export MAINFRAME_ROOT="/opt/mainframe"
source "$MAINFRAME_ROOT/lib/common.sh"
EOF

# Make executable
sudo chmod +x /etc/profile.d/mainframe.sh

# Apply immediately (or log out and back in)
source /etc/profile.d/mainframe.sh

Project-Local Installation

Best for projects that need a specific MAINFRAME version.

# In your project directory
git clone https://github.com/gtwatts/mainframe.git .mainframe

# In your scripts, source relative to script location
#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/.mainframe/lib/common.sh"

Add to .gitignore (optional):

echo ".mainframe/" >> .gitignore

Git Submodule

Best for version-controlled projects.

# Add as submodule
git submodule add https://github.com/gtwatts/mainframe.git vendor/mainframe

# Initialize in cloned repos
git submodule update --init --recursive

In your scripts:

source "vendor/mainframe/lib/common.sh"

Docker

Best for containerized environments.

# Dockerfile
FROM bash:5.2

# Install MAINFRAME
RUN git clone https://github.com/gtwatts/mainframe.git /opt/mainframe

# Set environment
ENV MAINFRAME_ROOT=/opt/mainframe

# Source in entrypoint
ENTRYPOINT ["/bin/bash", "-c", "source $MAINFRAME_ROOT/lib/common.sh && exec \"$@\"", "--"]

---

Shell Configuration

Environment Variables

Variable	Default	Description
MAINFRAME_ROOT	required	Path to MAINFRAME installation
MAINFRAME_OUTPUT	text	Output format: text or json
MAINFRAME_LOG_LEVEL	info	Log level: debug, info, warn, error
MAINFRAME_COLOR	auto	Color output: auto, always, never

Lazy Loading (Performance)

For faster shell startup, use lazy loading:

# In ~/.bashrc - only load when needed
export MAINFRAME_ROOT="$HOME/.mainframe"
mainframe() {
    source "$MAINFRAME_ROOT/lib/common.sh"
    mainframe "$@"
}

Selective Loading

Load only specific libraries:

export MAINFRAME_ROOT="$HOME/.mainframe"

# Load only what you need
source "$MAINFRAME_ROOT/lib/pure-string.sh"
source "$MAINFRAME_ROOT/lib/json.sh"

---

Verifying Installation

Basic Check

# Check version
mainframe version

# Expected output:
# MAINFRAME v5.0
# 2,000+ functions | 77 libraries | Pure Bash

Function Test

# Test core functions
trim_string "  hello  "       # Should output: hello
json_object "name=test"       # Should output: {"name":"test"}
timestamp                     # Should output: 2024-01-15T10:30:00
uuid                          # Should output: a UUID string

Full Test Suite

# Run all tests (requires bats)
cd "$MAINFRAME_ROOT"
git submodule update --init   # Get bats-core
./tests/bats/bin/bats tests/

# Expected: 3000+ tests, 0 failures

---

Updating

Standard Update

cd "$MAINFRAME_ROOT"
git pull origin main

Update with Submodule

git submodule update --remote vendor/mainframe

Check for Updates

cd "$MAINFRAME_ROOT"
git fetch origin
git log HEAD..origin/main --oneline  # Shows new commits

---

Uninstalling

User Installation

# Remove MAINFRAME
rm -rf ~/.mainframe

# Remove from ~/.bashrc (edit manually or use sed)
sed -i '/MAINFRAME/d' ~/.bashrc

System-Wide

sudo rm -rf /opt/mainframe
sudo rm -f /etc/profile.d/mainframe.sh

---

Troubleshooting

"mainframe: command not found"

Cause: MAINFRAME_ROOT not set or common.sh not sourced.

Fix:

export MAINFRAME_ROOT="$HOME/.mainframe"
source "$MAINFRAME_ROOT/lib/common.sh"

"bash: syntax error"

Cause: Using bash version < 4.0.

Check:

bash --version

Fix (macOS):

brew install bash
# Add /opt/homebrew/bin/bash to /etc/shells
# Change default: chsh -s /opt/homebrew/bin/bash

"Functions not available"

Cause: Sourcing before setting MAINFRAME_ROOT.

Fix: Set MAINFRAME_ROOT first:

# Correct order
export MAINFRAME_ROOT="$HOME/.mainframe"
source "$MAINFRAME_ROOT/lib/common.sh"

"Permission denied"

Cause: Missing execute permissions or wrong ownership.

Fix:

chmod -R u+rX ~/.mainframe

"git clone failed"

Cause: Network issues or SSH not configured.

Fix: Use HTTPS instead:

git clone https://github.com/gtwatts/mainframe.git ~/.mainframe

---

Next Steps

• Quick Start - Get productive in 5 minutes
• Library Reference - Explore all libraries
• AI Agent Integration - For autonomous systems

---

MAINFRAME · The AI-Native Bash Runtime

Home · Quick Start · Library Reference