command

Category: Shell Operations

Namespace: web.shell.command

Description

Executes a Windows command-line command (via cmd.exe) and captures its output. Can run commands in hidden mode (capturing output) or visible mode (showing command window).

Syntax

const output = await web.shell.command({
    command: 'dir',
    workingDir: 'C:\\',
    showWindow: false,
    windowBehavior: 3
});

Parameters

• command (required) - Command to execute (will be run via cmd.exe)
• workingDir (optional) - Working directory for the command (default: application directory)
• showWindow (optional) - Show command window to user (default: false)
• windowBehavior (optional) - Window close behavior when showWindow is true: 0 = immediate close, -1 = wait for keypress, N = auto-close after N seconds (default: 3)

Returns

Promise<string> - Returns a promise that resolves with the command output as a string

Examples

Simple example

const output = await web.shell.command({
    command: 'dir'
});
console.log('Directory listing:', output);

Run command with working directory

const output = await web.shell.command({
    command: 'dir /b',
    workingDir: 'C:\\Windows\\System32'
});
console.log('System32 files:', output);

Execute batch operations

// Run multiple commands in sequence
const output = await web.shell.command({
    command: 'echo Starting... && dir && echo Done!'
});
console.log(output);

Show command window to user

// Show visible command window (useful for interactive commands)
const output = await web.shell.command({
    command: 'ping google.com',
    showWindow: true,
    windowBehavior: 5  // Auto-close after 5 seconds
});
// Note: When showWindow is true, output capture is limited

Wait for user keypress

// Show window and wait for user to press a key before closing
const output = await web.shell.command({
    command: 'echo Processing complete!',
    showWindow: true,
    windowBehavior: -1  // Wait for keypress
});

Immediate close

// Show window but close immediately after command finishes
const output = await web.shell.command({
    command: 'dir',
    showWindow: true,
    windowBehavior: 0  // Close immediately
});

Use Cases

• Execute system commands and capture output
• Run batch scripts or command sequences
• Get directory listings programmatically
• Execute command-line tools
• Run system utilities and capture results

Notes

• Commands are executed via cmd.exe /C (hidden mode or immediate close)
• Has a 30-second timeout to prevent hanging
• When showWindow is false, output is captured and returned
• When showWindow is true, a visible command window appears
• windowBehavior only applies when showWindow is true:
  • 0 = Immediate close after command completes
  • -1 = Wait for user keypress before closing (adds pause command)
  • N (positive number) = Auto-close after N seconds (uses timeout /t N)
  • Default is 3 seconds
• Use && to chain multiple commands
• Relative paths in workingDir are resolved from application directory
• Security: Be careful with user-provided commands to avoid command injection
• Use web.shell.execute() for launching applications/opening files/folders
• Use web.shell.command() when you need to run commands and capture their output