Executes a command in an interactive pseudo-terminal (PTY) with support for terminal features like colors, cursor positioning, and interactive input.
Method Signature await sandbox . execInteractive ( command : string , options ?: PtyOptions ): Promise < ExecResult >
Parameters Command to execute in the PTY. Typically used for interactive programs like shells, text editors, or TUI applications.
PTY configuration options Maximum execution time in milliseconds
Environment variables for the command
Working directory for the command
Terminal width in columns
Input to send to the command’s stdin
Returns Raw terminal output including ANSI escape codes for colors and formatting
Standard error output (usually empty for PTY commands)
Exit code from the command
Examples Run interactive shell command const result = await sandbox . execInteractive ( 'ls --color=always' ); // Output includes ANSI color codes for colored file listing console . log ( result . stdout );
Execute with custom terminal size const result = await sandbox . execInteractive ( 'htop' , { cols: 120 , rows: 40 , timeout: 1000 });
const result = await sandbox . execInteractive ( 'python3' , { input: 'print("Hello from Python") \n exit() \n ' }); console . log ( result . stdout );
Run vim in headless mode const result = await sandbox . execInteractive ( 'vim' , { input: 'iHello World \x1b :wq \n ' , timeout: 5000 });
Capture colored output // Run a command that produces colored output const result = await sandbox . execInteractive ( 'npm test' , { env: { FORCE_COLOR: '1' } }); // The stdout contains ANSI escape codes // You can render this in a terminal or strip the codes console . log ( result . stdout );
When to Use Use execInteractive when:
Running commands that require a PTY (interactive shells, vim, htop)
Capturing colored terminal output (test frameworks, build tools)
Working with TUI applications
Sending input to interactive programs
Use regular exec for:
Non-interactive commands
When you don’t need ANSI escape codes
Better performance for simple commands
Terminal Features PTY execution enables:
ANSI escape codes - Colors, cursor positioning, formattingTerminal size - Commands see proper COLUMNS and LINES env varsRaw mode - No line buffering, immediate character inputJob control - Ctrl+C, Ctrl+Z signal handlingTerminal type - TERM environment variable set