Terminal UI (TUI)

ScriptIt provides a beautiful and intuitive Terminal User Interface (TUI) for interactive script management and execution. The TUI offers a visual way to browse, select, and execute scripts with real-time output monitoring.

Overview

The TUI is built using the blessed library and provides a full-screen terminal interface with multiple panels, keyboard navigation, and real-time script execution monitoring.

bash

# Launch TUI (default command)
scriptit run
scriptit  # Same as above

# Launch TUI with custom configuration
scriptit run --config custom.config.js --scripts-dir src/scripts

Interface Layout

The TUI consists of several panels arranged in a user-friendly layout:

┌─────────────────────────────────────────────────────────────────────┐
│ [C]onfig | [F]iles | [Tab] Focus | [Enter] Run | [j/k] Navigate | [Q]uit │ ← Control Panel
├─────────────────────────────────────────────────────────────────────┤
│ ┌─ Scripts ─────────┐ ┌─ Configuration ─┐                           │
│ │ • hello.js        │ │ Config: Default │                           │
│ │ • deploy.ts       │ │ Scripts: ./scr… │                           │
│ │ • backup.js       │ │ Temp: ./tmp     │                           │
│ │ • utils/clean.js  │ │ Env Vars: 12    │                           │
│ │                   │ │ Exclude: *.test │                           │
│ └───────────────────┘ └─────────────────┘                           │
├─────────────────────────────────────────────────────────────────────┤
│ ┌─ Output (ACTIVE) ─────────────────────────────────────────────────┐ │
│ │ TUI initialized. Use [↑↓] or [j/k] to navigate...                │ │
│ │ 🚀 Starting: hello.js                                            │ │
│ │   Hello from ScriptIt!                                           │ │
│ │   ✅ Script completed successfully                                │ │
│ │                                                                   │ │
│ └───────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Panels

1. Control Panel

The top panel displays available keyboard shortcuts and commands:

[C]onfig - Toggle configuration panel visibility
[F]iles - Toggle file list panel visibility
[Tab] - Switch focus between panels
[Enter] - Execute selected script
[j/k] - Navigate using vim-style keys
[R]efresh - Refresh script list
[Q]uit - Exit the TUI

2. Scripts Panel

The scripts panel shows all available scripts in your scripts directory:

Features:

Hierarchical display - Shows directory structure
Relative paths - Clean, readable script paths
Selection indicator - Highlights currently selected script
Scrollable list - Navigate through many scripts
Real-time filtering - Respects exclude patterns

Navigation:

↑/↓ or j/k - Move selection up/down
Enter - Execute selected script
Home/End - Jump to first/last script

3. Configuration Panel (Toggle)

The configuration panel displays current settings and can be toggled with C:

Information Displayed:

Config File - Shows loaded configuration file or "Default"
Scripts Directory - Relative path to scripts directory
Temp Directory - Relative path to temporary directory
Environment Variables - Count of loaded environment variables
Exclude Patterns - Active exclude patterns for filtering

4. Output Panel

The output panel shows real-time script execution output:

Features:

Colored output - Preserves console colors from scripts
Real-time updates - Shows output as it happens
Scrollable history - Navigate through previous output
Execution status - Clear success/failure indicators
Script results - Displays returned values from scripts

Navigation:

j/k - Scroll output up/down when focused
Tab - Switch focus to/from output panel

Keyboard Controls

Global Controls

Key	Action	Description
`q`, `Q`, `Ctrl+C`	Quit	Exit the TUI application
`Tab`	Switch Focus	Toggle between Scripts and Output panels
`c`, `C`	Toggle Config	Show/hide configuration panel
`f`, `F`	Toggle Files	Show/hide file list panel
`r`, `R`	Refresh	Reload script list from directory

Scripts Panel Controls

Key	Action	Description
`↑`, `k`	Move Up	Select previous script
`↓`, `j`	Move Down	Select next script
`Enter`	Execute	Run the selected script
`Home`	First Script	Jump to first script in list
`End`	Last Script	Jump to last script in list

Output Panel Controls

Key	Action	Description
`j`	Scroll Down	Scroll output down
`k`	Scroll Up	Scroll output up
`Page Down`	Page Down	Scroll down one page
`Page Up`	Page Up	Scroll up one page

Features

Script Discovery

The TUI automatically discovers scripts in your configured scripts directory:

Recursive scanning - Finds scripts in subdirectories
Pattern filtering - Respects exclude patterns from configuration
File type support - Supports .js, .ts, and other configured extensions
Real-time updates - Refresh with R to see new scripts

Real-time Execution

When you execute a script, the TUI provides:

Immediate feedback - Shows execution start/end
Live output streaming - See output as it happens
Colored console output - Preserves script color formatting
Error handling - Clear error messages and stack traces
Result display - Shows script return values

Visual Feedback

The TUI provides rich visual feedback:

Panel borders - Color-coded panel borders
Focus indicators - Clear indication of active panel
Status messages - Informative status updates
Progress indicators - Shows script execution progress
Color coding - Different colors for different message types

Configuration

TUI-Specific Options

Configure TUI behavior in your scriptit.config.js:

javascript

export default {
  // TUI configuration
  tui: {
    enabled: true,              // Enable TUI by default
    theme: 'default',           // Color theme
    refreshInterval: 1000,      // Auto-refresh interval (ms)
    showHiddenFiles: false,     // Show hidden files
    defaultFocus: 'scripts'     // Default focused panel
  },
  
  // Display configuration
  display: {
    showRelativePaths: true,    // Show relative paths in scripts list
    maxPathLength: 50,          // Truncate long paths
    showFileExtensions: true,   // Show file extensions
    groupByDirectory: false     // Group scripts by directory
  }
}

Environment Variables

Control TUI behavior with environment variables:

bash

# Disable TUI and use CLI mode
scriptit run --no-tui

# Force TUI even in debug mode
scriptit run --force-tui

# Enable debug mode for TUI
SCRIPTIT_DEBUG=true scriptit run

Usage Examples

Basic TUI Usage

bash

# Launch TUI with default settings
scriptit run

# Navigate to a script using arrow keys or j/k
# Press Enter to execute the selected script
# Press q to quit

Custom Configuration

bash

# Use custom scripts directory
scriptit run --scripts-dir src/automation

# Use custom configuration file
scriptit run --config production.config.js

# Combine options
scriptit run --config prod.config.js --scripts-dir scripts --tmp-dir temp

Development Workflow

bash

# 1. Initialize project with TUI-friendly structure
scriptit init

# 2. Create some scripts
mkdir -p scripts/utils
echo 'export async function execute(context) { 
  const console = context.console || global.console;
  console.log("Hello from TUI!"); 
}' > scripts/hello.js

# 3. Launch TUI
scriptit run

# 4. Navigate and execute scripts interactively

Debugging with TUI

bash

# Enable debug mode to see detailed information
SCRIPTIT_DEBUG=true scriptit run

# The TUI will show additional debug information:
# - Runtime detection details
# - Configuration loading process
# - Script discovery process
# - Execution environment details

Advanced Features

Script Metadata Display

The TUI can display script metadata when available:

javascript

// my-script.js
export const description = "This description appears in the TUI";
export const author = "Your Name";
export const version = "1.0.0";

export async function execute(context) {
  // Script implementation
}

Interactive Environment Variable Prompting

The TUI now supports interactive collection of environment variables through beautiful modal dialogs, providing the same functionality as the CLI but with a visual interface.

When a script requires environment variables, the TUI displays modal dialogs:

┌─────────────────────────────────────────────────────────────────────┐
│                          🔐 Environment Variable                    │
│                                                                     │
│  Enter your API key:                                               │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ ********                                                    │   │
│  └─────────────────────────────────────────────────────────────┘   │
│  [Enter] Submit • [Escape] Cancel • [Tab] Empty value             │
└─────────────────────────────────────────────────────────────────────┘

Declarative Variable Definition

Scripts can declare required environment variables:

javascript

// interactive-script.js
export const description = "Script with environment prompts";

// Define required environment variables
export const variables = [
  { name: 'API_KEY', message: 'Enter your API key:', type: 'password' },
  { name: 'USER_NAME', message: 'Enter your username:', type: 'input' },
  'ENVIRONMENT',  // Shorthand for simple variables
  'DEBUG_MODE'
];

export async function execute(context) {
  const console = context.console || global.console;
  
  // Variables are automatically collected and available
  console.log(`Username: ${context.env.USER_NAME}`);
  console.log(`Environment: ${context.env.ENVIRONMENT}`);
  console.log(`API Key: ${context.env.API_KEY ? '***hidden***' : 'Not set'}`);
  
  return { success: true };
}

Smart Variable Detection

The TUI automatically detects which variables need to be collected:

Skip existing - Variables already set in environment are not prompted
Batch collection - Collects multiple variables in sequence
Type-aware prompting - Password fields are masked, input fields are visible
Cancellable - Users can skip variables or cancel the entire process

Variable Types

The TUI supports different input types:

Password Fields:

javascript

{ name: 'API_KEY', type: 'password', message: 'Enter API key:' }

Input is masked with * characters
Content is hidden from display
Values are not logged for security

Input Fields:

javascript

{ name: 'USER_NAME', type: 'input', message: 'Enter username:' }

Regular text input
Content is visible as typed
Default type if not specified

Keyboard Controls:

Enter - Submit the current value
Escape - Skip this variable (sets empty value)
Tab - Submit empty value explicitly
Backspace - Delete characters
Arrow Keys - Navigate within input field

Visual Feedback:

🔐 Icon - Indicates password fields
📝 Icon - Indicates regular input fields
Color coding - Yellow for passwords, cyan for input
Progress indication - Shows which variable is being collected

Example Workflow

javascript

// deployment-script.js
export const description = "Deploy with environment prompts";

export const variables = [
  { name: 'DEPLOY_ENV', message: 'Target environment (prod/staging):', type: 'input' },
  { name: 'API_TOKEN', message: 'Deployment API token:', type: 'password' },
  { name: 'CONFIRM_DEPLOY', message: 'Confirm deployment (yes/no):', type: 'input' }
];

export async function execute(context) {
  const console = context.console || global.console;
  
  // Validate input
  if (context.env.CONFIRM_DEPLOY?.toLowerCase() !== 'yes') {
    console.warn('Deployment cancelled by user');
    return { cancelled: true };
  }
  
  console.info(`🚀 Deploying to ${context.env.DEPLOY_ENV}...`);
  
  // Use the collected variables
  const response = await deploy({
    environment: context.env.DEPLOY_ENV,
    token: context.env.API_TOKEN
  });
  
  console.log('✅ Deployment successful!');
  return response;
}

Security Features

No logging - Prompted values are never displayed in output logs
Memory isolation - Values are cleared after script execution
Visual masking - Password fields show * characters only
Process isolation - Values are only available during script execution

Multi-Panel Layout

The TUI supports different layout modes:

bash

# Hide configuration panel for more space
# Press 'C' to toggle configuration panel

# Hide file list to focus on output
# Press 'F' to toggle file list panel

# Switch focus between panels
# Press 'Tab' to switch focus

Output Management

The output panel provides advanced features:

Automatic scrolling - Follows new output automatically
Manual navigation - Use j/k to scroll through history
Clear indicators - Visual separation between script runs
Error highlighting - Errors are clearly marked
Result formatting - Script results are nicely formatted

Troubleshooting

Common Issues

TUI doesn't start:

bash

❌ Error initializing TUI: Terminal not supported
💡 Try running with --no-tui flag
💡 Ensure your terminal supports ANSI colors

Scripts not showing:

bash

# Check if scripts directory exists
ls -la scripts/

# Check exclude patterns in config
scriptit run --debug

# Refresh script list
# Press 'R' in TUI to refresh

Keyboard not working:

bash

# Ensure terminal supports keyboard input
# Try different terminal emulator
# Check if running in proper TTY

Debug Mode

Enable debug mode for detailed TUI information:

bash

SCRIPTIT_DEBUG=true scriptit run

Debug mode shows:

Terminal capabilities
Script discovery process
Configuration loading
Keyboard event handling
Panel rendering details

Terminal Compatibility

The TUI works best with modern terminal emulators:

✅ Fully Supported:

iTerm2 (macOS)
Terminal.app (macOS)
Windows Terminal
GNOME Terminal
Konsole
Alacritty
Hyper

⚠️ Limited Support:

Basic terminals without color support
Very old terminal emulators
Some CI/CD environments

❌ Not Supported:

Non-interactive environments
Terminals without TTY support

Integration with Other Features

Console Colors

The TUI preserves colored console output from scripts:

javascript

// colored-script.js
export async function execute(context) {
  const console = context.console || global.console;
  
  console.log('Regular message');    // White
  console.error('Error message');    // Red  
  console.warn('Warning message');   // Yellow
  console.info('Info message');      // Blue
  console.debug('Debug message');    // Gray
}

Environment Variables

The TUI displays environment information in the configuration panel:

javascript

// env-script.js
export async function execute(context) {
  const console = context.console || global.console;
  
  console.log('Environment:', context.env.NODE_ENV);
  console.log('API Key:', context.env.API_KEY ? '***' : 'Not set');
  console.log('Database:', context.env.DATABASE_URL ? 'Connected' : 'Not configured');
}

Cross-Runtime Support

The TUI works consistently across all supported runtimes:

bash

# TUI with Bun (fastest)
scriptit --runtime=bun run

# TUI with Deno (secure)
scriptit --runtime=deno run

# TUI with Node.js (compatible)
scriptit --runtime=node run

Best Practices

1. Organize Scripts

Structure your scripts for better TUI navigation:

scripts/
├── development/
│   ├── setup.js
│   └── test.js
├── deployment/
│   ├── build.js
│   └── deploy.js
└── utilities/
    ├── cleanup.js
    └── backup.js

2. Use Descriptive Names

Choose clear, descriptive script names:

javascript

// ✅ Good - clear purpose
export const description = "Deploy application to production";

// ❌ Avoid - unclear purpose
export const description = "Script";

3. Provide Feedback

Give users clear feedback during execution:

javascript

export async function execute(context) {
  const console = context.console || global.console;
  
  console.info('🚀 Starting deployment...');
  console.log('📦 Building application...');
  console.log('🔄 Uploading files...');
  console.log('✅ Deployment complete!');
}

4. Handle Errors Gracefully

Provide clear error messages:

javascript

export async function execute(context) {
  const console = context.console || global.console;
  
  try {
    // Script logic
    console.log('✅ Operation successful');
  } catch (error) {
    console.error('❌ Operation failed:', error.message);
    throw error; // Re-throw for TUI error handling
  }
}

CLI Commands - Command-line interface
Console Colors - Colored output features
Configuration - TUI configuration options
Getting Started - Basic usage guide

Terminal UI (TUI) ​

Overview ​

Interface Layout ​

Panels ​

1. Control Panel ​

2. Scripts Panel ​

3. Configuration Panel (Toggle) ​

4. Output Panel ​

Keyboard Controls ​

Global Controls ​

Scripts Panel Controls ​

Output Panel Controls ​

Features ​

Script Discovery ​

Real-time Execution ​

Visual Feedback ​

Configuration ​

TUI-Specific Options ​

Environment Variables ​

Usage Examples ​

Basic TUI Usage ​

Custom Configuration ​

Development Workflow ​

Debugging with TUI ​

Advanced Features ​

Script Metadata Display ​

Interactive Environment Variable Prompting ​

Modal Prompting Interface ​

Declarative Variable Definition ​

Smart Variable Detection ​

Variable Types ​

Modal Controls ​

Example Workflow ​

Security Features ​

Multi-Panel Layout ​

Output Management ​

Troubleshooting ​

Common Issues ​

Debug Mode ​

Terminal Compatibility ​

Integration with Other Features ​

Console Colors ​

Environment Variables ​

Cross-Runtime Support ​

Best Practices ​

1. Organize Scripts ​

2. Use Descriptive Names ​

3. Provide Feedback ​

4. Handle Errors Gracefully ​

Related Documentation ​

Terminal UI (TUI)

Overview

Interface Layout

Panels

1. Control Panel

2. Scripts Panel

3. Configuration Panel (Toggle)

4. Output Panel

Keyboard Controls

Global Controls

Scripts Panel Controls

Output Panel Controls

Features

Script Discovery

Real-time Execution

Visual Feedback

Configuration

TUI-Specific Options

Environment Variables

Usage Examples

Basic TUI Usage

Custom Configuration

Development Workflow

Debugging with TUI

Advanced Features

Script Metadata Display

Interactive Environment Variable Prompting

Modal Prompting Interface

Declarative Variable Definition

Smart Variable Detection

Variable Types

Modal Controls

Example Workflow

Security Features

Multi-Panel Layout

Output Management

Troubleshooting

Common Issues

Debug Mode

Terminal Compatibility

Integration with Other Features

Console Colors

Environment Variables

Cross-Runtime Support

Best Practices

1. Organize Scripts

2. Use Descriptive Names

3. Provide Feedback

4. Handle Errors Gracefully

Related Documentation