TUI Automation with tuistory

A Playwright-like testing framework for terminal user interfaces.

Setup

Ensure tuistory is installed:

# Check if installed
which tuistory || (bun add -g tuistory || npm install -g tuistory)

CLI Usage

tuistory provides a CLI for interacting with terminal sessions from the command line or shell scripts.

Quick Start

# Launch Claude Code
tuistory launch "claude" -s claude --cols 100 --rows 30

# Wait for it to load
tuistory -s claude wait "Claude Code" --timeout 15000

# Type a prompt
tuistory -s claude type "what is 2+2? reply with just the number"
tuistory -s claude press enter

# Wait for Claude's response using regex (matches any digit)
tuistory -s claude wait "/[0-9]+/" --timeout 30000

# Get terminal snapshot
tuistory -s claude snapshot --trim
# Output:
# ╭─────────────────────────────────────────────────────────────────────────────────╮
# │ ● Claude Code                                                                   │
# ╰─────────────────────────────────────────────────────────────────────────────────╯
#
# > what is 2+2? reply with just the number
#
# 4
#
# ────────────────────────────────────────────────────────────────────────────────────
# > 

# Close the session
tuistory -s claude close

Debugging Node.js with tuistory

# Launch Node.js debugger (assuming app.js has a debugger statement)
tuistory launch "node inspect app.js" -s debug --cols 80

# Wait for debugger to start and continue to breakpoint
tuistory -s debug wait "Break on start"
tuistory -s debug type "cont"
tuistory -s debug press enter
tuistory -s debug wait "break in"
tuistory -s debug snapshot --trim

# Print stack trace with bt (backtrace)
tuistory -s debug type "bt"
tuistory -s debug press enter
tuistory -s debug snapshot --trim
# Output:
# #0 getPrice app.js:13:2
# #1 calculateTotal app.js:7:15
# #2 processOrder app.js:2:16

# Enter REPL mode to inspect variables
tuistory -s debug type "repl"
tuistory -s debug press enter
tuistory -s debug type "item"
tuistory -s debug press enter
tuistory -s debug snapshot --trim
# Output:
# > item
# { name: 'Widget', price: 25, quantity: 2 }

# Clean up
tuistory -s debug close

CLI Commands Reference

tuistory launch <command>     # Start a terminal session
tuistory snapshot             # Get terminal text content
tuistory type <text>          # Type text character by character
tuistory press <key> [keys]   # Press key(s): enter, ctrl c, alt f4
tuistory click <pattern>      # Click on text matching pattern
tuistory wait <pattern>       # Wait for text (supports /regex/)
tuistory wait-idle            # Wait for terminal to stabilize
tuistory scroll <up|down>     # Scroll the terminal
tuistory resize <cols> <rows> # Resize terminal
tuistory close                # Close a session
tuistory sessions             # List active sessions
tuistory daemon-stop          # Stop the background daemon

Options

-s, --session <name>  # Session name (required for most commands)
--cols <n>            # Terminal columns (default: 80)
--rows <n>            # Terminal rows (default: 24)
--env <key=value>     # Environment variable (repeatable)
--timeout <ms>        # Wait timeout in milliseconds
--trim                # Trim whitespace from snapshot
--json                # Output as JSON

Tips for Successful Automation

Run snapshot after every command – Terminal applications are stateful and may show dialogs, prompts, or errors. Always check the current state:

tuistory -s mysession press enter
tuistory -s mysession snapshot --trim  # See what happened

Handle interactive dialogs – Many CLI applications show first-run dialogs (trust prompts, terms acceptance, login screens). You need to navigate these before your automation can proceed:

# Example: Claude Code may show trust/terms dialogs on first run
tuistory launch "claude" -s claude
tuistory -s claude snapshot --trim          # Check current state
tuistory -s claude press enter              # Accept dialog
tuistory -s claude snapshot --trim          # Verify it worked

Ensure applications are authenticated – Some CLIs require login. Run authentication commands first:

tuistory -s claude type "/login"
tuistory -s claude press enter
tuistory -s claude snapshot --trim          # Follow login prompts

Use wait for async operations – Don’t assume commands complete instantly:

tuistory -s mysession type "long-running-command"
tuistory -s mysession press enter
tuistory -s mysession wait "Done" --timeout 60000  # Wait for completion
tuistory -s mysession snapshot --trim

Debug with frequent snapshots – When automation fails, add snapshots between each step to see where it went wrong.