Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including pot-js with all npm packages installed. Try it out:

var potJs = require("pot-js")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

pot-js v0.0.0-beta.51

Process management module


Build Status

Process management module


Table of Contents


forever and pm2 are great third-party process management tools, but they are not module friendly. Saying if you are writing a CLI service tool, you may need to built-in a process management module for handling process monitor, run as a daemon, stop, scale, reload, and then you could just focus on developing your service logic. So I created this module.


  • Automatically restart process if it crashes. Like forever
  • Able to scale or reload instances with zero down time. Like pm2
  • Provides both CLI and Node.js module API
  • Supports isolated workspaces
  • User friendly interactive CLI
  • Easy to extend
  • Built-in powerful logger system


$ npm install pot-js

For global CLI command, please add -g option

$ npm install -g pot-js

CLI Reference

pot <command> [options]

  pot start [entry]             Spawn and monitor a process
  pot restart [name]            Restart a process
  pot restartall                Restart all processes
  pot reload [name]             Reload a process
  pot reloadall                 Reload all processes
  pot stop [name]               Stop a process
  pot stopall                   Stop all processes
  pot scale [name] [instances]  Scale up/down a process
  pot list                      List processes                     [aliases: ls]
  pot log [name] [category]     Show log
  pot show [name]               Show process information
  pot flush [name]              Remove log files
  pot flushall                  Remove all log files

  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]

Node.js module API Reference


Spawn and monitor a process.

  • args (String|String[]): List of string arguments. Defaults to [].
  • baseDir (String): The base directory for resolving modules or directories. Defaults to the current working directory.
  • cluster (Boolean): Enforce using cluster mode. If not set, it will automatically set to true when spawning a Node.js related process.
  • config (String): Path to the config file. Defaults to .potrc.
  • cwd (String): Current working directory. Defaults to process.cwd().
  • daemon (Boolean): Run as a daemon. Defaults to false.
  • entry (String): Entry script path. Defaults to ./index.js.
  • env (Object): Environment variables object. Defaults to process.env.
  • events (Object): Defining scripts by event hooks. Like scripts in package.json. Here are available event hooks:
    • spawn: New child process has been spawned
    • start: The monitor has started
    • stop: The monitor has fully stopped and the process is killed
    • crash: The monitor has crashed (too many restarts or spawn error)
    • sleep: The monitor is sleeping
    • exit: Child process has exited
    • stdout: Child process stdout has emitted data
    • stderr: Child process stderr has emitted data
    • warn: Child process has emitted an error
  • execArgs (String|String[]): Execution arguments. Defaults to [].
  • execPath (String): Execution Path. Defaults to process.execPath, which returns the absolute pathname of the executable that started the Node.js process. i.e. /usr/local/bin/node.
  • force (Boolean): Enforce restart even if the process is exists. Defaults to false.
  • inspect (Boolean|String|Object): Enable node inspector. Require Node.js >= v6.3.0. Defaults to false.
  • instances (Number): Cluster instances. Defaults to 1.
  • logLevel (String|Object): Log level. See pot-logger for detail. Here are available levels:
    • ALL
    • TRACE
    • DEBUG (default in development mode)
    • INFO (default in production mode)
    • WARN
    • ERROR
    • FATAL
    • OFF
  • logsDir (String): Log files directory. In daemon mode, log messages will write to some .log files.
  • maxRestarts (Number): How many restarts are allowed within 60s.
  • monitorProcessTitle (String): Monitor process title. Defaults to "node".
  • name (String): Process monitor name. Should be unique. Defaults to the basename of baseDir.
  • production (Boolean): Production mode. Short hand for setting NODE_ENV="production" env. Defaults to true.
  • watch (Boolean|Object): Enable watch mode. Defaults to false. Here are available props for object config:
    • enable (Boolean): Enable watch. Defaults to true.
    • dirs (String|String[]): Defining watching directories.
    • ignoreDotFiles (Boolean): Ignore watching .* files. Defaults to true.
    • ignoreNodeModulesDir (Boolean): Ignore watching node_modules directory. Defaults to true.
  • workspace (String): Workspace.


API to communicate with monitors


  • Connection.getNames(options)
  • Connection.getByName(name, options)
  • Connection.getState(name, options)
  • Connection.getAllInstances(options)
  • Connection.flushOffline()
  • connection#getState(instanceId)
  • connection#restart()
  • connection#reload(options)
  • connection#scale(number)
  • connection#flush()
  • connection#disconnect()
  • connection#requestStopServer(options)


Command lines interface helper functions


  • Operators.start(options)
  • Operators.restart(options)
  • Operators.restartAll(options)
  • Operators.reload(options)
  • Operators.reloadAll(options)
  • Operators.stop(options)
  • Operators.stopAll(options)
  • Operators.scale(options)
  • Operators.list(options)
  • Operators.log(options)
  • Operators.flush(options)
  • Operators.flushAll(options)


Config and CLI json schemas



pot-js commands descriptor. Useful to extend or modify command via createCli()

A command may contain these props:

  • command (String): A string representing the command. eg: stop [name]
  • description (String): Command description
  • schema (Object): The JSON schema of options and positional arguments
  • operator (Function): The operator function of the command


createCli(pkg, commands)

A helper function to create CLI, built on top of yargs





RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free