execute

Category: Shell Operations

Namespace: web.shell.execute

Description

Opens a file, URL, or executable using the Windows ShellExecute API. Uses the default associated program for the file type.

Syntax

const success = await web.shell.execute({
    filePath: 'document.pdf',
    arguments: ''
});

Parameters

• filePath (required) - File path, URL, or executable to open
• arguments (optional) - Command-line arguments to pass to the executable
• workingDir (optional) - Working directory (currently not used by implementation)

Returns

Promise<boolean> - Returns a promise that resolves with true if successful, false with error message otherwise

Examples

Open file with default program

const success = await web.shell.execute({
    filePath: 'C:\\Documents\\report.pdf'
});

if (success) {
    console.log('PDF opened successfully');
}

Open URL in default browser

const success = await web.shell.execute({
    filePath: 'https://www.example.com'
});

if (success) {
    console.log('Browser opened');
}

Execute program with arguments

// Open Notepad with a specific file
const success = await web.shell.execute({
    filePath: 'notepad.exe',
    arguments: 'C:\\temp\\notes.txt'
});

Open email client

// Open default email client with pre-filled email
const success = await web.shell.execute({
    filePath: 'mailto:support@example.com?subject=Help Request'
});

Use Cases

• Open documents with their default programs
• Launch URLs in the default web browser
• Open email client with pre-filled information
• Execute external programs
• Open files for viewing or editing

Notes

• Uses Windows ShellExecute API with "open" verb
• Automatically uses the default program associated with the file type
• Works with file paths, URLs (http://, https://, mailto:, etc.)
• Returns detailed error messages for common failures
• The workingDir parameter is defined but not currently used
• File paths can be relative or absolute
• Does not wait for the opened program to close
• Use web.shell.execute() for launching applications/opening files/folders
• Use web.shell.command() when you need to run commands and capture their output