About

Dependency-free promise based 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: 'n/a' }]  
*/

//By PID and fetch additional info via WMIC (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

<Promise> (<obj> option = {}) : <obj>[]

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

⚙️ Options

• 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"]

  Filter Name	Valid Operators	Valid Values
  STATUS	eq, ne	RUNNING
  IMAGENAME	eq, ne	Image name
  PID	eq, ne, gt, lt, ge, le	PID value
  SESSION	eq, ne, gt, lt, ge, le	Session number
  SESSIONNAME	eq, ne	Session name
  CPUTIME	eq, ne, gt, lt, ge, le	CPU time in the format HH:MM:SS, where MM and SS are between 0 and 59 and HH is any unsigned number
  MEMUSAGE	eq, ne, gt, lt, ge, le	Memory usage in KB
  USERNAME	eq, ne	Any valid user name
  SERVICES	eq, ne	Service name
  WINDOWTITLE	eq, ne	Window title
  MODULES	eq, ne	DLL name

💡 More details in the official tasklist doc.

Named export

<Promise> getProcessInfo(string|number process, <obj> option = {}) : <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 WMIC.
See getAdditionalInfoFromWMIC() for more details.

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

<Promise> isProcessRunning(string|number process, <obj> option = {}) : bool

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.

<Promise> hasProcess(string|number process, <obj> option = {}) : bool

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%.

<Promise> getAdditionalInfoFromWMIC(number pid) : <obj>

Query WMIC 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.