Tape Scripting

TUIOS Tape is a domain-specific language (DSL) for automating terminal window management workflows. Create reproducible scripts that can be played back, tested in CI/CD, or shared with your team.

Overview

Tape scripts allow you to:

Automate workflows: Replay complex terminal operations with a single command
Test integrations: Verify TUIOS behavior in CI/CD pipelines
Create demos: Generate consistent presentations and tutorials
Document processes: Capture and share terminal workflows as executable code
Remote execution: Run scripts against live TUIOS sessions

Quick Start

Running Tape Scripts

# Interactive playback (watch it happen)
tuios tape play demo.tape

# Headless execution (for CI/CD)
tuios tape run script.tape

# Validate syntax without running
tuios tape validate script.tape

Your First Tape Script

Create hello.tape:

# Create a window and run a command
WindowManagementMode
NewWindow
Sleep 500ms

TerminalMode
Type "echo 'Hello from TUIOS!'"
Enter
Sleep 1s

Run it:

tuios tape play hello.tape

Core Concepts

Modes

TUIOS has two primary modes that determine how input is handled:

Window Management Mode

For managing windows, workspaces, and layouts:

WindowManagementMode
NewWindow          # Create windows
NextWindow         # Navigate between them
EnableTiling       # Change layouts

Terminal Mode

For sending input to the focused terminal:

TerminalMode
Type "ls -la"     # Type text
Enter              # Press Enter
Ctrl+c             # Send signals

Always switch modes explicitly before mode-specific actions.

Timing

Add pauses to let operations complete:

NewWindow
Sleep 500ms        # Wait for window creation

MinimizeWindow
Sleep 300ms        # Wait for animation

Duration formats:

500ms - Milliseconds
2s - Seconds
1.5s - Decimal seconds
1m - Minutes

Command Reference

Window Operations

NewWindow                    # Create new terminal window
CloseWindow                  # Close focused window
NextWindow                   # Focus next window
PrevWindow                   # Focus previous window
RenameWindow "My Terminal"  # Rename focused window
MinimizeWindow               # Minimize to dock
RestoreWindow                # Restore from dock

Workspace Management

SwitchWorkspace 2               # Switch to workspace 2 (1-9)
MoveToWorkspace 3               # Move window without following
MoveAndFollowWorkspace 2        # Move window and switch

Layout & Tiling

ToggleTiling        # Toggle tiling on/off
EnableTiling        # Explicitly enable
DisableTiling       # Explicitly disable

SnapLeft            # Snap to left half
SnapRight           # Snap to right half
SnapFullscreen      # Fullscreen

Keyboard Input

Requires Terminal Mode:

TerminalMode
Type "command text"    # Type a string
Enter                   # Press Enter
Space                   # Press Space
Tab                     # Press Tab
Backspace               # Press Backspace
Escape                  # Press Escape

# Navigation keys
Up
Down
Left
Right
Home
End

# Key combinations
Ctrl+c
Ctrl+Alt+t
Shift+Tab

Synchronization

Sleep 500ms                           # Fixed delay
Wait 1s                               # Alias for Sleep
WaitUntilRegex "pattern" 5000        # Wait for output (timeout in ms)

Complete Examples

Development Environment Setup

# Create a tiled development environment
WindowManagementMode
EnableTiling
Sleep 300ms

# Editor window
NewWindow
Sleep 500ms
TerminalMode
Type "vim main.go"
Enter
Sleep 800ms

# Build window
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "go build -watch"
Enter

# Test window
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "go test -v ./..."
Enter

Multi-Workspace Project

WindowManagementMode

# Workspace 1: Coding
SwitchWorkspace 1
EnableTiling
NewWindow
TerminalMode
Type "vim main.go"
Enter
Sleep 500ms

WindowManagementMode
NewWindow
TerminalMode
Type "go run ."
Enter

# Workspace 2: Testing
WindowManagementMode
SwitchWorkspace 2
NewWindow
TerminalMode
Type "go test -v ./..."
Enter

# Workspace 3: Git
WindowManagementMode
SwitchWorkspace 3
NewWindow
TerminalMode
Type "git status"
Enter

# Return to main workspace
WindowManagementMode
SwitchWorkspace 1

Conditional Waiting

WindowManagementMode
NewWindow
Sleep 500ms

TerminalMode
# Start a long-running build
Type "npm install"
Enter

# Wait for completion (up to 60 seconds)
WaitUntilRegex "completed" 60000

# Run after install
Type "npm start"
Enter

Advanced Features

Remote Execution

Execute tape scripts against a running TUIOS session:

# Execute against current session
tuios tape exec script.tape

# Execute against specific session
tuios tape exec --session mysession script.tape
tuios tape exec -s mysession script.tape

Use cases: Automation pipelines:

# Start session in background
tuios new automation &
sleep 2

# Execute setup script
tuios tape exec -s automation setup.tape

# Run tests
tuios tape exec -s automation test-workflow.tape

Development workflows:

# In terminal 1: Start TUIOS
tuios new dev

# In terminal 2: Send scripts to configure environment
tuios tape exec -s dev environment-setup.tape

Differences: `play` vs `exec`

Feature	`tape play`	`tape exec`
Starts TUIOS	Yes	No (requires running session)
Shows TUI	Yes	No (progress bar only)
Interactive	Yes	No
For automation	No	Yes
Session persistence	No	Yes (works with daemon)

Comments & Documentation

# Lines starting with # are comments
# Use them to document your scripts

# Setup section
WindowManagementMode
EnableTiling

# Main workflow
NewWindow
Sleep 500ms

String Literals

Supports multiple quote styles:

Type "double quotes"
Type 'single quotes'
Type `backticks`

# Escape sequences in double quotes
Type "Line 1\nLine 2\tTabbed"

Best Practices

1. Always Add Sleep After Actions

Give TUIOS time to process:

NewWindow
Sleep 500ms    # ✓ Good

MinimizeWindow
Sleep 300ms    # ✓ Good

2. Explicit Mode Switching

Always switch modes before mode-specific actions:

# ✓ GOOD
WindowManagementMode
NewWindow
TerminalMode
Type "ls"

# ✗ BAD (mode might be wrong)
NewWindow
Type "ls"

3. Use Consistent Timing

Window creation: 500ms
Window navigation: 200ms
Animations: 300ms
Workspace switches: 400ms

4. Document Complex Workflows

# Setup development environment
WindowManagementMode
EnableTiling

# Create editor window
NewWindow
TerminalMode
Type "vim main.go"
Enter
Sleep 800ms

# Create build window
WindowManagementMode
NewWindow
TerminalMode
Type "go build -watch"
Enter

5. Handle Long Operations

Use longer timeouts for slow operations:

TerminalMode
Type "npm install"
Enter
WaitUntilRegex "completed" 60000  # 60 second timeout

Use Cases

CI/CD Testing

Test TUIOS workflows in continuous integration:

#!/bin/bash
# test.sh
tuios tape run ci-test-suite.tape
if [ $? -eq 0 ]; then
    echo "Tests passed"
else
    echo "Tests failed"
    exit 1
fi

Demo Creation

Create consistent, repeatable demos:

tuios tape play conference-demo.tape

Onboarding & Training

Share executable workflows with new team members:

# onboarding.tape
# Shows new developers how to set up the project

WindowManagementMode
NewWindow
TerminalMode
Type "git clone https://github.com/user/repo.git"
Enter
WaitUntilRegex "done" 30000

Type "cd repo"
Enter
Type "make setup"
Enter

Documentation

Embed tape scripts in docs for interactive examples.

Troubleshooting

Script Not Working?

Check mode: Ensure you’re in the correct mode
Add delays: Increase Sleep durations
Validate syntax: Run tuios tape validate script.tape
Test regex: Verify WaitUntilRegex patterns match expected output

Common Errors

“Unknown command”
Check spelling and capitalization (commands are case-sensitive) “Unexpected token”
Check for missing quotes around strings “Timeout waiting for pattern”
Increase timeout or verify regex pattern

Get Started

Core Features

Advanced Features

Configuration

Guides

Documentation Index

​Overview

​Quick Start

​Running Tape Scripts

​Your First Tape Script

​Core Concepts

​Modes

​Window Management Mode

​Terminal Mode

​Timing

​Command Reference

​Window Operations

​Workspace Management

​Layout & Tiling

​Keyboard Input

​Synchronization

​Complete Examples

​Development Environment Setup

​Multi-Workspace Project

​Conditional Waiting

​Advanced Features

​Remote Execution

​Differences: play vs exec

​Comments & Documentation

​String Literals

​Best Practices

​1. Always Add Sleep After Actions

​2. Explicit Mode Switching

​3. Use Consistent Timing

​4. Document Complex Workflows

​5. Handle Long Operations

​Use Cases

​CI/CD Testing

​Demo Creation

​Onboarding & Training

​Documentation

​Troubleshooting

​Script Not Working?

​Common Errors

​See Also

Build docs developers (and LLMs) love

Overview

Quick Start

Running Tape Scripts

Your First Tape Script

Core Concepts

Modes

Window Management Mode

Terminal Mode

Timing

Command Reference

Window Operations

Workspace Management

Layout & Tiling

Keyboard Input

Synchronization

Complete Examples

Development Environment Setup

Multi-Workspace Project

Conditional Waiting

Advanced Features

Remote Execution

Differences: `play` vs `exec`

Comments & Documentation

String Literals

Best Practices

1. Always Add Sleep After Actions

2. Explicit Mode Switching

3. Use Consistent Timing

4. Document Complex Workflows

5. Handle Long Operations

Use Cases

CI/CD Testing

Demo Creation

Onboarding & Training

Documentation

Troubleshooting

Script Not Working?

Common Errors

See Also