ScriptTour

A professional Bash script player that executes and displays terminal commands with typewriter-like effects, perfect for creating engaging demos, tutorials, and presentations.

Overview

ScriptTour transforms static script files into dynamic, visually appealing terminal presentations. It simulates human typing, displays colorized output, and provides precise control over timing and appearance. The tool consists of two main components that can work independently or together:

• scripttour - Main script player for .script files
• typewriter.inc.sh - Standalone typewriter effect library

Features

Core Capabilities

• Typewriter Effects - Natural typing simulation with 11 speed levels (xxxfast to xxxslow)
• Smart Command Execution - Execute and display commands with real-time output
• Colored Output - Automatic color coding:
  • 🟨 Yellow for commands
  • 🟩 Green for comments
  • 🔴 Red for errors
• Flexible Script Control:
  • Silent command execution
  • Configurable pauses and delays
  • Comment display with word wrapping
  • Error code tracking in prompts

Advanced Features

• Custom Prompts - Configure username, hostname, and prompt format
• Speed Control - Independent speed settings for commands and comments
• Bash Completion - Full tab completion support for options and script files
• Source-Safe Library - Typewriter library can be sourced into other scripts
• Terminal Detection - Automatic color disable for non-TTY output

Installation

Quick Install (Recommended)

sudo sh -c 'cd /usr/share && git clone https://github.com/Open-Technology-Foundation/scripttour.git && ln -s /usr/share/scripttour/scripttour /usr/local/bin/scripttour && scripttour --help'

Manual Installation

# Clone the repository
git clone https://github.com/Open-Technology-Foundation/scripttour.git
cd scripttour

# Make scripts executable
chmod +x scripttour typewriter.inc.sh

# Option 1: Add to PATH
export PATH="$PATH:$(pwd)"

# Option 2: Create system-wide symlink
sudo ln -s "$(pwd)/scripttour" /usr/local/bin/scripttour

Enable Bash Completion

# For current session
source .bash_completion

# For permanent installation
sudo cp .bash_completion /etc/bash_completion.d/scripttour

Usage

Basic Command Structure

scripttour [OPTIONS] script.file

Command-Line Options

Option	Description	Default
-c, --clear	Clear screen before starting	Off
-w, --comment-cols COLS	Column width for comment wrapping	78
-o, --comment-speed SPEED	Comment typing speed	vfast
-m, --cmd-speed SPEED	Command typing speed	normal
-U, --username USER	Set prompt username	sysadmin
-H, --hostname HOST	Set prompt hostname	yatti
-v, --verbose	Increase output verbosity	-
-q, --quiet	Suppress non-error messages	-
-V, --version	Show version information	-
-h, --help	Display help message	-

Speed Options

From fastest to slowest: xxxfast xxfast xfast vfast fast normal slow vslow xslow xxslow xxxslow

Examples

# Basic playback
scripttour demo.script

# Fast comments, slow commands, custom prompt
scripttour -o xxfast -m slow -U admin -H prod-server demo.script

# Clear screen first, narrow comment width
scripttour -c -w 60 tutorial.script

# Presentation mode with dramatic timing
scripttour -c -o normal -m vslow presentation.script

Script File Format

ScriptTour uses .script files with a simple, intuitive syntax:

Syntax Elements

Syntax	Description	Example
command	Execute and display command	ls -la
#comment	Display comment with typewriter effect	# This is shown
##comment	Silent comment (ignored)	## Internal note
!command	Execute silently (no display)	!cd /tmp
!	Print empty line	!
number	Pause for N seconds	3
(empty line)	Pause for 0.25 seconds

Example Script File

#!/bin/bash
## This script demonstrates ScriptTour features

# Welcome to the ScriptTour demo!
# Let's explore some Linux commands

2

# First, let's see where we are
pwd

# Now let's list the files
ls -la

!echo "Setting up environment..." >/dev/null
3

# Let's check the system information
uname -a

# That's all for now!

Using the Typewriter Library

The typewriter.inc.sh script can be used standalone or sourced into other scripts.

Standalone Usage

# Basic usage
./typewriter.inc.sh "Hello, World!"

# With options
./typewriter.inc.sh -s fast -c 32 "Green text typing fast"
./typewriter.inc.sh -s slow -i 4 "    Indented slow text"

# From stdin
echo "Piped text" | ./typewriter.inc.sh -s normal
cat file.txt | ./typewriter.inc.sh -s xxfast

Sourcing in Scripts

#!/bin/bash
source /path/to/typewriter.inc.sh

# Use the typewriter function
typewriter -s normal "This types at normal speed"

# Use the tw wrapper with environment defaults
export TW_SPEED=fast TW_INDENT=2
tw "This uses environment settings"

Technical Details

Architecture

ScriptTour follows modern Bash best practices:

• Strict error handling with set -euo pipefail
• Proper variable scoping using local and declare
• Type-safe declarations with -i for integers, -A for arrays
• Source-safe design - can be safely sourced without conflicts
• POSIX-compatible where possible, Bash 5.2+ specific features clearly marked

File Structure

scripttour/
├── scripttour           # Main script player
├── typewriter.inc.sh    # Typewriter library
├── .bash_completion     # Bash completion definitions
├── .version            # Version tracking
├── example.script      # Example demonstration
├── README.md          # This file
├── LICENSE            # GPL-3.0 license
└── CLAUDE.md         # AI assistant instructions

Performance Considerations

• Minimal subshell usage for better performance
• Random delay variations for natural typing effect
• Efficient array operations using Bash built-ins
• Smart terminal detection to avoid unnecessary operations

Requirements

• OS: Ubuntu Linux or compatible distribution
• Bash: Version 5.0 or higher
• Utilities: Standard GNU coreutils (grep, sed, fmt)
• Terminal: Any terminal emulator with ANSI color support

Troubleshooting

Common Issues

Script not found: Ensure the script has execute permissions:

chmod +x scripttour typewriter.inc.sh

Colors not working: Check if output is to a terminal:

[[ -t 1 ]] && echo "Terminal detected" || echo "Not a terminal"

Command not found: Verify PATH or use full path:

/full/path/to/scripttour script.file

Contributing

Contributions are welcome! Please ensure your code follows our Bash Coding Style Guide:

1. Use 2-space indentation
2. Implement proper error handling
3. Add appropriate comments
4. Test with various script files
5. Update documentation as needed

Submit pull requests to: https://github.com/Open-Technology-Foundation/scripttour

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

See the LICENSE file for full details.

Author

Gary Dean [email protected] Open Technology Foundation (https://yatti.id)

Acknowledgments

Special thanks to the Bash community and all contributors who have helped improve ScriptTour.

---

ScriptTour - Making terminal presentations engaging and professional