Tape Scripting

TUIOS Tape is a domain-specific language (DSL) for automating terminal window management workflows. Tape scripts allow you to record, replay, and test complex TUIOS interactions programmatically.

Perfect for...

Recording and replaying terminal workflows
Automated testing
Demo recording
CI/CD automation
Documenting workflows

Running Tape Scripts

# Interactive mode (visible TUI) - watch automation happen
tuios tape play demo.tape

# Validate syntax
tuios tape validate demo.tape

# List saved recordings
tuios tape list

# Show a tape file
tuios tape show my-recording

Remote Execution

The tuios tape exec command allows you to run tape scripts against an already running TUIOS session. This is perfect for automation workflows where TUIOS is running in daemon mode.

# Execute against current session
tuios tape exec script.tape

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

Progress Display

Remote execution shows a progress indicator:

Executing script.tape... Progress: 5/12 [███████░░░░░░░░░░░░░] 41%

Use Cases

Automation pipelines:

#!/bin/bash
# Start a session
tuios new automation &
sleep 2

# Execute scripts
tuios tape exec -s automation setup.tape
tuios tape exec -s automation test-workflow.tape

# Cleanup
tuios kill-session automation

Development workflows:

# Terminal 1: Start TUIOS
tuios new dev

# Terminal 2: Send scripts
tuios tape exec -s dev environment-setup.tape

Differences from `tape play`

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)

Combining with CLI Commands

Remote tape execution works seamlessly with other CLI commands:

# Execute script then query state
tuios tape exec setup.tape
tuios session-info --json | jq '.total_windows'

# Create window via command, then run tape
tuios run-command NewWindow "dev"
tuios tape exec dev-setup.tape

See Sessions & Remote Control for more about controlling TUIOS from external scripts.

Basic Syntax

Comments

Lines starting with # are comments:

# This is a comment
NewWindow  # Create a window

Commands

Commands are case-sensitive:

NewWindow
Sleep 500ms
TerminalMode
Type "echo hello"
Enter

String Literals

Type "hello world"
Type 'hello world'
Type `hello world`

Durations

Sleep 500ms     # Milliseconds
Sleep 2s        # Seconds
Sleep 1.5s      # Decimal seconds

Mode Management

Important

TUIOS has two modes: Window Management Mode and Terminal Mode. Always switch modes explicitly before mode-specific commands!

WindowManagementMode

Switch to window management mode for managing windows.

WindowManagementMode

TerminalMode

Switch to terminal mode to send input to the focused window.

TerminalMode

Example workflow:

WindowManagementMode
NewWindow
TerminalMode
Type "ls -la"
Enter
WindowManagementMode

Window Operations

NewWindow

Create a new terminal window.

NewWindow
Sleep 500ms  # Give time for creation

CloseWindow

Close the currently focused window.

CloseWindow

NextWindow / PrevWindow

Navigate between windows.

NextWindow
Sleep 200ms

RenameWindow

Rename the focused window.

RenameWindow "My Terminal"

MinimizeWindow / RestoreWindow

Minimize and restore windows.

MinimizeWindow
Sleep 300ms
RestoreWindow

Tiling and Layout

ToggleTiling

Toggle tiling mode.

ToggleTiling

EnableTiling / DisableTiling

Explicitly control tiling mode.

EnableTiling
Sleep 300ms

When you record a tape, TUIOS automatically prepends DisableAnimations at the start and appends EnableAnimations at the end. This ensures tape playback is reproducible regardless of the user's animation settings.

Animation Sync

Tape playback automatically waits for animations to complete before executing the next command. This ensures smooth, synchronized execution even with animations enabled.

Snap Commands

Snap windows to positions.

SnapLeft
SnapRight
SnapFullscreen

Workspace Management

TUIOS supports 9 workspaces (1-9).

SwitchWorkspace

Switch to a workspace.

SwitchWorkspace 2
Sleep 400ms

MoveToWorkspace

Move window to workspace.

MoveToWorkspace 3

MoveAndFollowWorkspace

Move and follow.

MoveAndFollowWorkspace 2

Keyboard Input

Terminal Mode Required

Keyboard commands only work in Terminal Mode!

Type

Type text into terminal.

TerminalMode
Type "echo 'Hello, World!'"

Basic Keys

Enter
Space
Tab
Backspace
Delete
Escape

Up
Down
Left
Right
Home
End

Key Combinations

Ctrl+c
Ctrl+b
Alt+1
Shift+Tab
Ctrl+Alt+t

Timing

Sleep

Pause execution.

Sleep 500ms
Sleep 1s

WaitUntilRegex

Wait for terminal output to match a pattern.

TerminalMode
Type "ls -la"
Enter
WaitUntilRegex "\$" 3000  # Wait for prompt

Example Scripts

Basic Workflow

# Create a new window and run commands
WindowManagementMode
NewWindow
Sleep 500ms

TerminalMode
Type "ls -la"
Enter
Sleep 1s

Type "echo 'Done'"
Enter

Multi-Workspace Setup

# Setup workspace 1 - development
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "cd ~/project"
Enter

# Switch to workspace 2 - monitoring
WindowManagementMode
SwitchWorkspace 2
Sleep 400ms

NewWindow
Sleep 500ms
TerminalMode
Type "htop"
Enter

Tiling Demo

# Create tiled layout
WindowManagementMode
EnableTiling

NewWindow
Sleep 500ms
NewWindow
Sleep 500ms
NewWindow
Sleep 500ms

# Navigate and type in each
TerminalMode
Type "echo 'Window 1'"
Enter

WindowManagementMode
NextWindow
TerminalMode
Type "echo 'Window 2'"
Enter

Development Environment Setup

# Create development workspace
WindowManagementMode
EnableTiling

# Window 1: Editor
NewWindow
Sleep 500ms
TerminalMode
Type "nvim ."
Enter

# Window 2: Server
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "npm run dev"
Enter

# Window 3: Tests
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "npm test -- --watch"
Enter

# Window 4: Git
WindowManagementMode
NewWindow
Sleep 500ms
TerminalMode
Type "git status"
Enter

Recording Tapes

You can record your interactions:

Press Ctrl+B T r to start recording

Perform your workflow normally

Press Ctrl+B T s to stop recording

Tape is saved to ~/.local/share/tuios/tapes/

View your recordings:

tuios tape list
tuios tape show my-recording

Best Practices

Always Add Delays

Give TUIOS time to process animations and state changes

NewWindow
Sleep 500ms  # Wait for creation (GOOD)

NewWindow
# No sleep - next command might execute too soon (BAD)

Explicit Mode Switching

Always switch modes explicitly before mode-specific actions

# GOOD
WindowManagementMode
NewWindow
TerminalMode
Type "ls"

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

Use Comments

Document complex workflows

# Setup development environment
WindowManagementMode
EnableTiling

# Create editor window
NewWindow
Sleep 500ms

# Create terminal window
NewWindow
Sleep 500ms

CLI Reference

Tape command-line usage

Keybindings

Keybindings for manual control

Tape Scripting

CLI Reference

Keybindings

On this page