0
# Process Management
1

2
Core process lifecycle operations for managing Node.js applications with PM2. Provides starting, stopping, restarting, reloading, and deleting managed processes with support for multiple execution modes, clustering, and advanced configuration options.
3

4
## Capabilities
5

6
### Connection Management
7

8
Establish and manage connections to the PM2 daemon process.
9

10
```javascript { .api }
11
/**
12
 * Connect to PM2 daemon or launch a new one
13
 * @param callback - Called when connection is established or fails
14
 */
15
function connect(callback: (err: Error) => void): void;
16

17
/**
18
 * Connect to PM2 daemon with daemon mode control
19
 * @param noDaemonMode - If true, PM2 will not run as daemon and will die when script exits
20
 * @param callback - Called when connection is established or fails
21
 */
22
function connect(noDaemonMode: boolean, callback: (err: Error) => void): void;
23

24
/**
25
 * Disconnect from PM2 daemon
26
 */
27
function disconnect(): void;
28
```
29

30
**Usage Examples:**
31

32
```javascript
33
const pm2 = require('pm2');
34

35
// Standard connection (daemon mode)
36
pm2.connect((err) => {
37
  if (err) {
38
    console.error('Failed to connect:', err);
39
    process.exit(2);
40
  }
41
  console.log('Connected to PM2');
42
  // Perform operations...
43
  pm2.disconnect();
44
});
45

46
// No daemon mode (PM2 dies when script exits)
47
pm2.connect(true, (err) => {
48
  if (err) throw err;
49
  // PM2 will not persist after this script ends
50
});
51
```
52

53
### Process Starting
54

55
Start new processes with comprehensive configuration options.
56

57
```javascript { .api }
58
/**
59
 * Start a process from options object
60
 * @param options - Process configuration options
61
 * @param callback - Called with error and process information
62
 */
63
function start(options: StartOptions, callback: (err: Error, proc: Proc) => void): void;
64

65
/**
66
 * Start a process from script path
67
 * @param script - Path to script file
68
 * @param callback - Called with error and process information
69
 */
70
function start(script: string, callback: (err: Error, proc: Proc) => void): void;
71

72
/**
73
 * Start a process with script and options
74
 * @param script - Path to script file
75
 * @param options - Process configuration options
76
 * @param callback - Called with error and process information
77
 */
78
function start(script: string, options: StartOptions, callback: (err: Error, proc: Proc) => void): void;
79

80
/**
81
 * Start a process from JSON configuration file
82
 * @param jsonConfigFile - Path to JSON configuration file
83
 * @param callback - Called with error and process information
84
 */
85
function start(jsonConfigFile: string, callback: (err: Error, proc: Proc) => void): void;
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
// Start with options object
92
pm2.start({
93
  script: 'app.js',
94
  name: 'my-app',
95
  instances: 'max',
96
  exec_mode: 'cluster',
97
  env: {
98
    NODE_ENV: 'production',
99
    PORT: '3000'
100
  },
101
  watch: true,
102
  ignore_watch: ['node_modules', 'logs'],
103
  max_memory_restart: '1G',
104
  log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
105
}, (err, proc) => {
106
  if (err) throw err;
107
  console.log('Process started:', proc[0].pm2_env.name);
108
});
109

110
// Start from script path only
111
pm2.start('server.js', (err, proc) => {
112
  if (err) throw err;
113
  console.log('Server started');
114
});
115

116
// Start with script and options
117
pm2.start('worker.js', {
118
  name: 'background-worker',
119
  instances: 2,
120
  cwd: '/app/workers'
121
}, (err, proc) => {
122
  if (err) throw err;
123
  console.log('Worker processes started');
124
});
125

126
// Start from ecosystem file
127
pm2.start('ecosystem.config.js', (err, proc) => {
128
  if (err) throw err;
129
  console.log('Ecosystem loaded');
130
});
131
```
132

133
### Process Stopping
134

135
Stop running processes while keeping them in the PM2 process list.
136

137
```javascript { .api }
138
/**
139
 * Stop a process but leave metadata in PM2 list
140
 * @param process - Process name, ID, or "all" for all processes
141
 * @param callback - Called when process is stopped
142
 */
143
function stop(process: string | number, callback: (err: Error, proc: Proc) => void): void;
144
```
145

146
**Usage Examples:**
147

148
```javascript
149
// Stop by name
150
pm2.stop('my-app', (err, proc) => {
151
  if (err) throw err;
152
  console.log('Process stopped');
153
});
154

155
// Stop by ID
156
pm2.stop(0, (err, proc) => {
157
  if (err) throw err;
158
  console.log('Process 0 stopped');
159
});
160

161
// Stop all processes
162
pm2.stop('all', (err, proc) => {
163
  if (err) throw err;
164
  console.log('All processes stopped');
165
});
166
```
167

168
### Process Restarting
169

170
Restart processes with optional configuration updates.
171

172
```javascript { .api }
173
/**
174
 * Stop and restart a process
175
 * @param process - Process name, ID, or "all" for all processes
176
 * @param callback - Called when process is restarted
177
 */
178
function restart(process: string | number, callback: (err: Error, proc: Proc) => void): void;
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
// Restart specific process
185
pm2.restart('my-app', (err, proc) => {
186
  if (err) throw err;
187
  console.log('Process restarted');
188
});
189

190
// Restart all processes
191
pm2.restart('all', (err, proc) => {
192
  if (err) throw err;
193
  console.log('All processes restarted');
194
});
195
```
196

197
### Zero-Downtime Reload
198

199
Perform zero-downtime rolling restarts for cluster mode applications.
200

201
```javascript { .api }
202
/**
203
 * Zero-downtime rolling restart (cluster mode only)
204
 * @param process - Process name, ID, or "all" for all processes
205
 * @param callback - Called when reload is complete
206
 */
207
function reload(process: string | number, callback: (err: Error, proc: Proc) => void): void;
208

209
/**
210
 * Zero-downtime rolling restart with options
211
 * @param process - Process name, ID, or "all" for all processes
212
 * @param options - Reload configuration options
213
 * @param callback - Called when reload is complete
214
 */
215
function reload(process: string | number, options: ReloadOptions, callback: (err: Error, proc: Proc) => void): void;
216

217
interface ReloadOptions {
218
  /** Update environment variables from process.env before reloading */
219
  updateEnv?: boolean;
220
}
221
```
222

223
**Usage Examples:**
224

225
```javascript
226
// Standard reload
227
pm2.reload('cluster-app', (err, proc) => {
228
  if (err) throw err;
229
  console.log('Zero-downtime reload completed');
230
});
231

232
// Reload with environment update
233
pm2.reload('cluster-app', { updateEnv: true }, (err, proc) => {
234
  if (err) throw err;
235
  console.log('Reloaded with updated environment');
236
});
237

238
// Reload all cluster processes
239
pm2.reload('all', (err, proc) => {
240
  if (err) throw err;
241
  console.log('All cluster processes reloaded');
242
});
243
```
244

245
### Process Deletion
246

247
Remove processes from PM2 management completely.
248

249
```javascript { .api }
250
/**
251
 * Stop process and remove from PM2 list
252
 * @param process - Process name, ID, or "all" for all processes
253
 * @param callback - Called when process is deleted
254
 */
255
function delete(process: string | number, callback: (err: Error, proc: Proc) => void): void;
256
```
257

258
**Usage Examples:**
259

260
```javascript
261
// Delete specific process
262
pm2.delete('old-app', (err, proc) => {
263
  if (err) throw err;
264
  console.log('Process deleted from PM2');
265
});
266

267
// Delete by ID
268
pm2.delete(3, (err, proc) => {
269
  if (err) throw err;
270
  console.log('Process 3 deleted');
271
});
272

273
// Delete all processes
274
pm2.delete('all', (err, proc) => {
275
  if (err) throw err;
276
  console.log('All processes deleted');
277
});
278
```
279

280
### State Persistence
281

282
Save and restore process configurations across system restarts.
283

284
```javascript { .api }
285
/**
286
 * Save current process list to dump file
287
 * @param callback - Called when dump is complete
288
 */
289
function dump(callback: (err: Error, result: any) => void): void;
290

291
/**
292
 * Restore processes from saved dump file
293
 * @param callback - Called when resurrection is complete
294
 */
295
function resurrect(callback: (err: Error, result: any) => void): void;
296
```
297

298
**Usage Examples:**
299

300
```javascript
301
// Save current process list
302
pm2.dump((err, result) => {
303
  if (err) throw err;
304
  console.log('Process list saved to dump file');
305
});
306

307
// Restore saved processes
308
pm2.resurrect((err, result) => {
309
  if (err) throw err;
310
  console.log('Processes restored from dump');
311
});
312

313
// Typical workflow for persistence
314
pm2.connect((err) => {
315
  if (err) throw err;
316
  
317
  // Start your applications
318
  pm2.start('app.js', { name: 'my-app' }, (err) => {
319
    if (err) throw err;
320
    
321
    // Save the configuration
322
    pm2.dump((err) => {
323
      if (err) throw err;
324
      console.log('Configuration saved');
325
      pm2.disconnect();
326
    });
327
  });
328
});
329

330
// On system restart or in startup script
331
pm2.connect((err) => {
332
  if (err) throw err;
333
  
334
  // Restore all saved processes
335
  pm2.resurrect((err) => {
336
    if (err) throw err;
337
    console.log('All processes restored');
338
    pm2.disconnect();
339
  });
340
});
341
```
342

343
### System Integration
344

345
System-level operations for daemon management and startup integration.
346

347
```javascript { .api }
348
/**
349
 * Kill PM2 daemon (stops all processes)
350
 * @param callback - Called when daemon is killed
351
 */
352
function killDaemon(callback: (err: Error, processDescription: ProcessDescription) => void): void;
353

354
/**
355
 * Setup system startup script
356
 * @param platform - Target platform for startup script
357
 * @param callback - Called when startup is configured
358
 */
359
function startup(platform: Platform, callback: (err: Error, result: any) => void): void;
360

361
type Platform = 'ubuntu' | 'centos' | 'redhat' | 'gentoo' | 'systemd' | 'darwin' | 'amazon';
362
```
363

364
**Usage Examples:**
365

366
```javascript
367
// Kill PM2 daemon
368
pm2.killDaemon((err, result) => {
369
  if (err) throw err;
370
  console.log('PM2 daemon killed');
371
});
372

373
// Setup startup script
374
pm2.startup('systemd', (err, result) => {
375
  if (err) throw err;
376
  console.log('Startup script configured:', result);
377
});
378
```
379

380
## Core Types
381

382
```javascript { .api }
383
interface StartOptions {
384
  /** Process name for PM2 identification */
385
  name?: string;
386
  /** Script file path to execute */
387
  script?: string;
388
  /** Arguments passed to the script */
389
  args?: string | string[];
390
  /** Arguments passed to the interpreter */
391
  interpreter_args?: string | string[];
392
  /** Working directory for the process */
393
  cwd?: string;
394
  /** Environment variables */
395
  env?: { [key: string]: string };
396
  /** Number of instances (cluster mode) */
397
  instances?: number;
398
  /** Execution mode: 'fork' or 'cluster' */
399
  exec_mode?: string;
400
  /** Enable file watching for auto-restart */
401
  watch?: boolean | string[];
402
  /** Patterns to ignore when watching */
403
  ignore_watch?: string[];
404
  /** Merge cluster instance logs */
405
  merge_logs?: boolean;
406
  /** Stdout log file path */
407
  output?: string;
408
  /** Stderr log file path */
409
  error?: string;
410
  /** Log timestamp format */
411
  log_date_format?: string;
412
  /** PID file path */
413
  pid?: string;
414
  /** Auto restart on crash */
415
  autorestart?: boolean;
416
  /** Maximum restart attempts */
417
  max_restarts?: number;
418
  /** Memory restart threshold */
419
  max_memory_restart?: number | string;
420
  /** Minimum uptime before considering stable */
421
  min_uptime?: number;
422
  /** SIGKILL timeout in milliseconds */
423
  kill_timeout?: number;
424
  /** Delay between restarts */
425
  restart_delay?: number;
426
  /** Script interpreter */
427
  interpreter?: string;
428
  /** Wait for ready signal from process */
429
  wait_ready?: boolean;
430
  /** Force start even if already running */
431
  force?: boolean;
432
  /** Process namespace */
433
  namespace?: string;
434
}
435

436
interface Proc {
437
  name?: string;
438
  pm_id?: number;
439
  pid?: number;
440
  status?: string;
441
  restart_time?: number;
442
  created_at?: number;
443
  pm_uptime?: number;
444
  unstable_restarts?: number;
445
}
446
```