PM2 — Apply Actions to a Selected Process in Process File (JSON/JS/YAML)

Following this PM2 series, you’ve already learned how to manage your processes and how to declare an advanced JSON process file for a single or multiple applications. Declaring multiple applications in a single process file is a convenient way to keep your app definitions close together in a selected location.

This tutorial will show you how to act only on a single application from the list of multiple apps in your process file.

PM2 Series Overview


Within the previous tutorial showing you how to define multiple applications within a single process file, you’ve seen the following list of applications. For a handy reference, we name the file apps.json.


  "apps": [
      "name": "homepage",
      "script": "./server.js",
      "exec_mode": "cluster",
      "instances": 2,
      "node_args": "--max_old_space_size=8192"
      "name": "worker",
      "script": "./worker.js",
      "node_args": "--max_old_space_size=8192"
      "name": "api",
      "script": "./api.js"

The apps.json process file defines three applications, the homepage, worker and api with their individual script entry points and further custom attributes.

You can just go ahead and use the file with the PM2 command line utility and execute your desired action, like restart or reload. The problem: the action will be applied to every app in the apps.json file. Read on to get the trick on how to just act on a selected app out of that list.

Act on a Single Process in the Process File (JSON/JS/YAML)

The PM2 command line utility ships with the functionality to reference a single application within a process file using the --only <app-name> argument.

pm2 <action> apps.json --only api

# where <action> is one of PM2’s commands, like
#   start|restart|reload|startOrReload|stop|delete

Reference the process file with your PM2 related <action> and pass the --only argument with your specific application name that is defined within the process file. For example, if you want to start the worker process only, use the following command:

$ pm2 start apps.json --only worker
[PM2][WARN] Applications worker not running, starting...
[PM2] App [worker] launched (1 instances)
│ App name │ id │ mode    │ pid   │ status │ restart │ uptime │ cpu │ mem       │ watching │
│ worker   │ 0  │ cluster │ 14071 │ online │ 0       │ 0s     │ 0%  │ 19.5 MB   │ disabled │

The --only argument really just accepts a single application name. If you want to start two out of three applications, you need to separately act on both two and just skip the third one.


PM2 allows you to define advanced process files including complex configurations for different setups. Further, you can consolidate all your applications in a single process file. If you just want to act on a single application in your list, just reference the specific process by name using the --only argument.

Do you have further questions on PM2 or Node.js in general? Just let uns know on Twitter @futurestud_io or leave a comment below.

Make it rock & enjoy coding!

Explore the Library

Find interesting tutorials and solutions for your problems.