PM2 Commands

Start Processes

More than a couple of flags belongs in an ecosystem file rather than your shell history; the PM2 ecosystem generator writes one from a form.

List and Status

The restart counter (↺ in the list) climbing on its own means the app is crash-looping; read the error log before anything else.

Logs

PM2 captures each process's stdout and stderr to files under ~/.pm2/logs/.

PM2 does not rotate logs on its own, and a chatty app fills a disk quietly. Install pm2-logrotate on every server the first time you set one up.

Restart, Reload and Stop

stop keeps the entry (status stopped); delete forgets it. After any change you want back after a reboot, run pm2 save again.

Cluster Mode

Cluster mode runs several instances of the same Node app behind PM2's built-in load balancer, one per core with max. The app needs no code changes as long as it does not keep local state.

Cluster mode is Node-only, since it uses the Node cluster module. Sticky sessions and anything held in process memory (in-memory sessions, local caches) break across instances; move that state to Redis or the database first.

Save, Startup and Resurrect

Surviving a reboot is a two-step dance, and skipping the second step is the classic mistake.

So the full sequence is: pm2 startup, run the command it printed, get your apps running the way you want, then pm2 save. The hook restores whatever the last pm2 save captured, so rerun it after adding, deleting or renaming processes.

Environment Variables

PM2 snapshots the environment when a process first starts and reuses it on every restart. Changing a variable in the shell or in .bashrc does nothing until you restart with --update-env or delete and start fresh. This surprises everyone once.

Ecosystem File

ecosystem.config.js holds everything the start flags express, in a file you can commit. pm2 init writes a sample, or the PM2 ecosystem generator builds one from a form.

module.exports = {
  apps: [{
    name: "api",
    script: "./server.js",
    instances: "max",
    exec_mode: "cluster",
    max_memory_restart: "300M",
    args: "--port 3000",
    env: { NODE_ENV: "development" },
    env_production: { NODE_ENV: "production" },
  }],
};

Monitoring

pm2 monit is the fastest answer to "which process is eating the CPU". For alerting and history, PM2's hosted monitoring (pm2 plus) exists, but plain pm2 monit over SSH covers day-to-day checks.

Deployment and Updates

pm2 deploy reads a deploy section in the ecosystem file (host, repo, path, post-deploy command) and works fine for simple git-based deploys. Teams that outgrow it usually move to CI plus pm2 reload over SSH.

If you would rather have the init system own the process, with proper dependencies and journald logging, the pm2 to systemd converter turns an ecosystem file into unit files, and the systemctl cheat sheet covers managing them.

Gotchas

• pm2 startup alone does nothing at boot. It prints a command; run that command, then pm2 save. The saved dump is what gets restored, so save again after every change to the list.
• pm2 reload is only zero-downtime in cluster mode with two or more instances. In fork mode it is just a restart with a friendlier name.
• Restarts keep the environment from the first start. New or changed variables need pm2 restart api --update-env, or a delete and a fresh start.
• Logs are never rotated by default. pm2 install pm2-logrotate before the disk fills, and pm2 flush when it already has.
• --watch in production causes restart loops when the app writes into its own directory (logs, uploads). Use --ignore-watch, or better, no watch at all outside development.
• pm2: command not found in cron, CI or GitHub Actions usually means npm's global bin is not on that context's PATH; use the absolute path to the binary.
• pm2 kill takes down the daemon and every app with it. To remove one app, pm2 delete api.