ScriptTour

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

Features

• Typewriter Effects: Natural typing animation for commands and comments
• Real-time Execution: Commands run live with output captured in real-time
• Customizable Speed: 11 speed levels from xxxfast to xxxslow
• Smart Prompts: Shows username, hostname, working directory, and exit codes
• Flexible Syntax: Simple script format with comments, pauses, and silent commands
• Bash Completion: Tab completion for options and script files

Installation

# Clone the repository
git clone https://github.com/yourusername/scripttour.git
cd scripttour

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

# Optional: Add to PATH
ln -s "$(pwd)/scripttour" ~/.local/bin/scripttour

# Optional: Install bash completion
source .bash_completion

Quick Start

Create a demo script file demo.script:

# Welcome to ScriptTour!
echo "Hello, World!"

# Let's see what's in this directory
ls -la

# Create a file
echo "ScriptTour rocks!" > message.txt

# Read it back
cat message.txt

# Clean up
rm message.txt

Run it:

./scripttour demo.script

Script Syntax

ScriptTour uses a simple line-based format:

Syntax	Description	Example
# comment	Displayed comment (green, typed out)	# Installing dependencies
## comment	Silent comment (ignored)	## TODO: add error handling
command	Execute and display command	npm install express
!command	Silent execution (no display)	!export PATH=$PATH:/usr/local/bin
!	Print empty line	!
number	Pause for N seconds	3
(empty line)	Pause for 0.25 seconds

Special Features

• First shebang ignored: #!/bin/bash at the start is skipped
• Exit codes tracked: Prompts show the last command's exit code
• Word wrapping: Comments automatically wrap to terminal width
• State persistence: Variables and functions persist across commands

Command Line Options

scripttour [OPTIONS] file.script

Options:
  -c, --clear              Clear screen before starting
  -w, --comment-cols COLS  Set comment width (default: terminal width)
  -o, --comment-speed SPEED Set comment typing speed (default: vfast)
  -m, --cmd-speed SPEED    Set command typing speed (default: normal)
  -U, --username USER      Set prompt username (default: sysadmin)
  -H, --hostname HOST      Set prompt hostname (default: yatti)
  -v, --verbose            Increase verbosity
  -q, --quiet              Suppress messages
  -V, --version            Show version
  -h, --help               Show help

Speed levels: xxxfast, xxfast, xfast, vfast, fast, normal,
              slow, vslow, xslow, xxslow, xxxslow

Examples

Basic Demo

# Run with default settings
./scripttour example.script

# Fast typing with custom prompt
./scripttour -o xfast -m fast -U admin -H prod-server demo.script

# Clear screen first, narrow comments
./scripttour -c -w 60 tutorial.script

Advanced Script

#!/bin/bash
## example.script - Database setup demo

# Setting up PostgreSQL database
!export DB_NAME=myapp

# Create database
createdb $DB_NAME

# Run migrations
2
psql $DB_NAME < schema.sql

# Verify tables
psql $DB_NAME -c "\dt"

# Success!
echo "Database $DB_NAME is ready"

Typewriter Library

The typewriter.inc.sh script can be used standalone:

# Direct execution
./typewriter.inc.sh "Hello, World!"
./typewriter.inc.sh --speed fast "Quick typing"
./typewriter.inc.sh --rainbow "Colorful text"

# Source in your scripts
source typewriter.inc.sh
typewriter "This text appears with typewriter effect"
tw --speed slow "Short alias works too"

Testing

Run the comprehensive test suite:

# Run all tests
./tests/test_runner.sh

# Run specific test category
./tests/test_runner.sh basic
./tests/test_runner.sh pipe
./tests/test_runner.sh prompt

# Performance benchmarks
./tests/performance_test.sh
./tests/performance_comparison.sh

Project Structure

scripttour/
├── scripttour              # Main script player
├── typewriter.inc.sh        # Typewriter effect library
├── example.script           # Example demo script
├── tests/
│   ├── test_runner.sh       # Test suite runner
│   ├── performance_test.sh  # Performance benchmarks
│   └── fixtures/           # Test script files
├── .bash_completion        # Bash completion support
└── CLAUDE.md               # AI assistant instructions

Use Cases

• Software Demos: Show your application in action
• Tutorial Creation: Step-by-step command-line tutorials
• Documentation: Living documentation that proves commands work
• Training Materials: Interactive learning experiences
• Conference Talks: Smooth, rehearsed terminal presentations
• CI/CD Demos: Demonstrate deployment pipelines

Contributing

Contributions are welcome! The codebase follows strict Bash coding standards:

• Always use set -euo pipefail
• 2-space indentation
• Local variables in functions
• Comprehensive error handling

See CLAUDE.md for detailed development guidelines.

License

GNU General Public License v3.0 - see LICENSE file for details.

Author

Created with attention to detail for the terminal presentation connoisseur.