win-tasklist v2.2.0

About

Wrapper for the Windows tasklist command.

Note about locale:

Most Windows commands change their output based on system's locale, which can be sometimes difficult when you are trying to parse the output of a non-English system. This module tries to be system-locale-independent as much as possible in order to be able to parse the tasklist output. Unfortunately some returned properties will remain locale-dependent.

Example

Get a specific process information:

import { getProcessInfo } from "win-tasklist";

console.log( await getProcessInfo("explorer.exe",{verbose: true}) );
/*
  [{ process: 'explorer.exe',
      pid: 6960,
      sessionType: 'console',
      sessionNumber: 1,
      memUsage: 169783296,
      state: 'running',
      user: 'skynet\\xan',
      cpuTime: '0:02:15',
      windowTitle: null }]  
*/

//By PID and fetch additional info via WMI (args and dir of origin)

console.log( await getProcessInfo(15640,{verbose: true, extended: true}) );
/*
  { process: 'firefox.exe',
    pid: 15640,
    sessionType: 'console',
    sessionNumber: 1,
    memUsage: 80269312,
    state: 'running',
    user: 'SKYNET\\Xan',
    cpuTime: '0:00:00',
    windowTitle: 'OleMainThreadWndName',
    args: '-contentproc -isForBrowser -prefsHandle 2688 ...',
    origin: 'C:\\Program Files\\Mozilla Firefox'}  
*/

Is process running ?

import { isProcessRunning } from "win-tasklist";

console.log( await isProcessRunning("firefox.exe") );
//true or false

List them all:

import tasklist from "win-tasklist";

console.log( await tasklist() );
/*
  [ { process: 'system idle process',
      pid: 0,
      sessionType: 'services',
      sessionNumber: 0,
      memUsage: 8192 },
    { process: 'system',
      pid: 4,
      sessionType: 'services',
      sessionNumber: 0,
      memUsage: 2580480 }, 
      ... 100 more items ]
*/

Installation

npm install win-tasklist

API

⚠️ This module is only available as an ECMAScript module (ESM) starting with version 2.0.0. Previous version(s) are CommonJS (CJS) with an ESM wrapper.

Default export

(option?: obj): Promise<obj[]>

Wrapper to the tasklist command. Returns an Array of object.

• verbose (default: false) if false will return the following properties : process, pid, sessionType, sessionNumber, memUsage (bytes). if true will additionally return the following properties : state, user, cpuTime, windowTitle. ⚠️ Keep in mind using the verbose option might impact performance.
• remote (default: null) Name or IP address of a remote computer. Must be used with user and password options below.
• user (default: null) Username or Domain\Username.

• password (default: null) User's password.

• uwpOnly (default: false) List only Windows Store Apps (UWP). ⚠️ NB: With this option to true and verbose to false; tasklist only returns process, pid, memUsage (bytes) and AUMID.

• filter (default: [])

  Array of string. Each string being a filter.

  eg filter for listing only running processes : ["STATUS eq RUNNING"]

💡 More details in the official tasklist doc.

Named export

getProcessInfo(process: string | number, option?: obj): Promise<obj[] | obj>

process can either be a PID (number or number as a string) or an imagename (string). Same option as default export minus filter and with the addition of extended (boolean).

extended adds args and origin (dir) properties from WMI. See getAdditionalInfoFromWMI() for more details.

Returns an Array of object or a single obj if you are searching by PID (number or number as a string).

isProcessRunning(process: string | number, option?: obj): Promise<boolean>

process can either be a PID (number or number as a string) or an imagename (string). Same option as default export minus filter and verbose.

Return true if the specified process is running (meaning it has the status RUNNING), false otherwise.

Equivalent of filter IMAGENAME/PID eq %process% and STATUS eq RUNNING.

hasProcess(process: string | number, option?: obj): Promise<boolean>

process can either be a PID (number or number as a string) or an imagename (string). Same option as default export minus filter and verbose.

Return true if the specified process is loaded (meaning it is listed in the tasklist), false otherwise.

Equivalent of filter IMAGENAME/PID eq %process%.

getAdditionalInfoFromWMI(pid: number): Promise<obj>

Query WMI for process' commandline and location (dirpath). Return an object:

  {
    args: string, //command line
    origin: string | null //location (dirpath)
  }

In case information can not be accessed due to privileges restriction then origin will be null and args will be empty.