powershell-utils

powershell-utils

Utilities for executing PowerShell commands

Install

npm install powershell-utils

Usage

import {executePowerShell, powerShellPath} from 'powershell-utils';

const {stdout} = await executePowerShell('Get-Process');
console.log(stdout);

console.log(powerShellPath());
//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'

API

powerShellPath()

Returns: string

Get the PowerShell executable path on Windows.

import {powerShellPath} from 'powershell-utils';

const psPath = powerShellPath();
//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'

canAccessPowerShell()

Returns: Promise<boolean>

Check if PowerShell is accessible on Windows.

This checks if the PowerShell executable exists and has execute permissions. Useful for detecting restricted environments where PowerShell may be disabled by administrators.

import {canAccessPowerShell} from 'powershell-utils';

if (await canAccessPowerShell()) {
	console.log('PowerShell is available');
} else {
	console.log('PowerShell is not accessible');
}

executePowerShell(command, options?)

Returns: Promise<{stdout: string, stderr: string}>

Execute a PowerShell command.

import {executePowerShell} from 'powershell-utils';

const {stdout} = await executePowerShell('Get-Process');
console.log(stdout);

command

Type: string

The PowerShell command to execute.

options

Type: object

The below option and also all options in Node.js child_process.execFile() are supported.

powerShellPath

Type: string
Default: powerShellPath()

Path to PowerShell executable. Useful when calling from WSL or when PowerShell is in a non-standard location.

encoding

Type: string
Default: 'utf8'

Character encoding for stdout and stderr.

executePowerShell.argumentsPrefix

Type: string[]

Standard PowerShell arguments that prefix the encoded command: ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']

Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use createArguments() instead.

executePowerShell.encodeCommand(command)

Returns: string

Encode a PowerShell command as Base64 UTF-16LE.

This encoding prevents shell escaping issues and ensures complex commands with special characters are executed reliably.

command

Type: string

The PowerShell command to encode.

import {executePowerShell} from 'powershell-utils';

const encoded = executePowerShell.encodeCommand('Get-Process');

executePowerShell.escapeArgument(value)

Returns: string

Escape a string argument for use in PowerShell single-quoted strings.

value

Type: unknown

The value to escape.

import {executePowerShell} from 'powershell-utils';

const escaped = executePowerShell.escapeArgument("it's a test");
//=> "'it''s a test'"

// Use in command building
const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;

executePowerShell.createArguments(command)

Returns: string[]

Create the full arguments array for PowerShell execution.

Combines argumentsPrefix with the encoded command. Useful when using spawn(), execFile(), or other process execution methods.

command

Type: string

The PowerShell command.

import {spawn} from 'node:child_process';
import {powerShellPath, executePowerShell} from 'powershell-utils';

const args = executePowerShell.createArguments('Get-Process');
spawn(powerShellPath(), args);

executePowerShellSync(command, options?)

Returns: string

Execute a PowerShell command synchronously.

import {executePowerShellSync} from 'powershell-utils';

const stdout = executePowerShellSync('Get-Process');
console.log(stdout);

command

Type: string

The PowerShell command to execute.

options

Type: object

The below option and also all options in Node.js child_process.execFileSync() are supported.

powerShellPath

Type: string
Default: powerShellPath()

Path to PowerShell executable.

encoding

Type: string
Default: 'utf8'

Character encoding for the output.