execInteractive

Execute an interactive command with PTY support

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 · string · required

Command to execute in the PTY. Typically used for interactive programs like shells, text editors, or TUI applications.

options · PtyOptions

PTY configuration options

Show PtyOptions

timeout · number

Maximum execution time in milliseconds

env · Record<string, string>

Environment variables for the command

cwd · string

Working directory for the command

sessionId · string

Session ID to execute in

cols · number · default: "80"

Terminal width in columns

rows · number · default: "24"

Terminal height in rows

input · string

Input to send to the command’s stdin

Returns

ExecResult · object

Show ExecResult fields

stdout · string

Raw terminal output including ANSI escape codes for colors and formatting

stderr · string

Standard error output (usually empty for PTY commands)

exitCode · number

Exit code from the command

success · boolean

True if exitCode is 0

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
});

Send input to interactive program

const result = await sandbox.execInteractive('python3', {
  input: 'print("Hello from Python")\nexit()\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, formatting
• Terminal size - Commands see proper COLUMNS and LINES env vars
• Raw mode - No line buffering, immediate character input
• Job control - Ctrl+C, Ctrl+Z signal handling
• Terminal type - TERM environment variable set

Related Methods

• exec - Execute non-interactive commands
• execStream - Stream command output
• proxyTerminal - Full terminal proxy for web clients