Start apps

Introduction

PM2 is a production process manager for Node.js.

Fork mode

pm2 start app.js --name my-api
pm2 start server.js -- --port 3000

Common flags

FlagEffect
--nameName the process
--attachAttach to logs after start
--no-daemonRun in the foreground
--no-vizionSkip git metadata parsing

Git parsing is opt-in: set PM2_ENABLE_GIT_PARSING=true to use vizion.

See: Process management

Cluster mode

pm2 start app.js -i max
pm2 start app.js -i 4 --name api

Cluster flags

FlagEffect
-i maxStart one worker per CPU
-i 0Legacy equivalent of -i max
--wait-readyWait for the app ready signal

Cluster mode balances traffic across workers.

See: Cluster mode

Ecosystem file

pm2 init simple
pm2 start ecosystem.config.js
pm2 start ecosystem.config.js --only api
pm2 start ecosystem.config.js --env production

Ecosystem commands

CommandEffect
pm2 ecosystemGenerate an ecosystem file
pm2 initAlias for pm2 ecosystem
pm2 start ecosystem.config.jsStart every declared app
--only apiStart one named app
--env productionUse the named env block

An ecosystem file declares apps, environment blocks and cluster settings.

See: Application declaration

Start flags

FlagEffect
--watchRestart when files change
--max-memory-restart 200MRestart above a memory limit
--cron '0 30 9 * * *'Restart on a cron schedule
--update-envRefresh environment on restart
--no-autorestartDisable automatic restarts
--only apiStart one app from the file

See: CLI reference

Process management

List processes

CommandEffect
pm2 listShow all processes
pm2 jlistPrint the process list as JSON
pm2 prettylistPrint a formatted JSON list

See: CLI reference

Inspect process

CommandEffect
pm2 describe 0Show details for one process
pm2 show apiShow details for a named process
pm2 pid apiPrint process IDs
pm2 env 0Print a process's environment

See: CLI reference

Monitor

CommandEffect
pm2 monitLive metrics and logs in the terminal

See: CLI reference

Stop & restart

CommandEffect
pm2 stop apiStop one process
pm2 stop allStop all processes
pm2 restart apiRestart one process
pm2 restart allRestart all processes
pm2 restart api --update-envRestart with fresh env vars
pm2 reset apiReset one restart counter
pm2 reset allReset all restart counters

See: Process management

Reload & scale

pm2 reload api
pm2 scale api 4

Cluster commands

CommandEffect
pm2 reload allZero-downtime reload of all apps
pm2 reload apiZero-downtime reload of one app
pm2 scale api 4Resize a cluster to four workers
pm2 scale api +2Add two workers

Reload avoids downtime for clustered apps; fork mode falls back to a restart.

See: Cluster mode

Delete processes

CommandEffect
pm2 delete apiRemove one process from PM2
pm2 delete allRemove all processes from PM2

Deleting stops the process and drops it from the process list.

See: Process management

Logs

Stream logs

pm2 logs
pm2 logs --json --lines 100
pm2 logs api --err

Log options

FlagEffect
--jsonOutput JSON lines
--lines NShow the last N lines
--errOnly error output
--outOnly standard output

Streaming uses PM2's raw format by default.

See: Log management

Clear & rotate

CommandEffect
pm2 flushEmpty all log files
pm2 reloadLogsReopen logs after rotation
pm2 logrotateGenerate a logrotate config

Run pm2 reloadLogs after an external rotation.

See: Log management

Restart & watch

Watch files

pm2 start app.js --watch
pm2 start app.js --watch --ignore-watch node_modules

Watch flags

FlagEffect
--watchWatch the app directory
--watch-delay 1Debounce restarts by 1s

Use --watch in development; production restarts belong to reloads and deploys.

See: Watch & restart

Restart policies

FlagEffect
--max-memory-restart 200MRestart above 200 MB RSS
--cron '0 30 9 * * *'Restart daily at 09:30
--update-envApply new env vars on restart
--no-autorestartLeave crashed processes down

PM2 restarts a process that exits by default.

See: Watch & restart

Signals

CommandEffect
pm2 sendSignal SIGUSR2 apiSignal one named process
pm2 sendSignal SIGUSR2 allSignal every process

Use app-level signal handlers for graceful shutdown or reload hooks.

See: CLI reference

Startup & persistence

Startup script

CommandEffect
pm2 startupPrint a script for your init system
pm2 unstartupRemove the startup script

Run the command printed by pm2 startup to register the script.

See: Startup

Save & resurrect

CommandEffect
pm2 savePersist the current list
pm2 resurrectRestore the saved list

Run pm2 save again whenever the process list changes.

See: Startup

Dumps

CommandEffect
pm2 dumpWrite the process dump
pm2 cleardumpDelete the process dump

pm2 save writes the dump that startup uses at boot.

See: CLI reference

Deployment & modules

Deploy

CommandEffect
pm2 deploy ecosystem.config.js productionDeploy a release
pm2 deploy ecosystem.config.js production updatePull and restart
pm2 deploy ecosystem.config.js production revertRoll back a release
pm2 deploy ecosystem.config.js production listList releases

See: CLI reference

Modules

CommandEffect
pm2 install <module>Install a PM2 module
pm2 uninstall <module>Remove an installed module
pm2 plusLink the daemon to PM2 Plus

See: CLI reference

Configuration

CommandEffect
pm2 set key valueSet a configuration value
pm2 get keyRead a configuration value

Ecosystem files also declare per-app env blocks.

See: CLI reference

Daemon management

Daemon lifecycle

CommandEffect
pm2 updateReload the daemon and its apps
pm2 pingCheck that the daemon is running
pm2 killStop the daemon and its processes

updatePM2 is the legacy alias for pm2 update.

See: Update PM2

Report & dashboard

CommandEffect
pm2 reportPrint a diagnostic report
pm2 dashboardTerminal dashboard, like monit

See: CLI reference

Static server

CommandEffect
pm2 serve dist 8080Serve a directory on a port
pm2 serve dist 8080 --spaFall back to index.html
pm2 serve dist 8080 --name siteName the served process

See: CLI reference

0 Comments for this cheatsheet. Write yours!