0
# TypeScript Definitions
1

2
Complete TypeScript interface and type definitions for PM2, providing full type safety for programmatic usage. All interfaces match the actual PM2 implementation and provide comprehensive type coverage for process management, configuration, and monitoring operations.
3

4
## Core Process Interfaces
5

6
### StartOptions Interface
7

8
Comprehensive configuration options for starting PM2 processes.
9

10
```typescript { .api }
11
interface StartOptions {
12
  /** Process name for PM2 identification */
13
  name?: string;
14
  
15
  /** Script file path to execute */
16
  script?: string;
17
  
18
  /** Arguments passed to the script */
19
  args?: string | string[];
20
  
21
  /** Arguments passed to the interpreter */
22
  interpreter_args?: string | string[];
23
  
24
  /** Working directory for the process */
25
  cwd?: string;
26
  
27
  /** Environment variables */
28
  env?: { [key: string]: string };
29
  
30
  /** Number of instances for cluster mode */
31
  instances?: number;
32
  
33
  /** Execution mode: 'fork' or 'cluster' */
34
  exec_mode?: string;
35
  
36
  /** Enable file watching for auto-restart */
37
  watch?: boolean | string[];
38
  
39
  /** Patterns to ignore when watching files */
40
  ignore_watch?: string[];
41
  
42
  /** Merge cluster instance logs into single files */
43
  merge_logs?: boolean;
44
  
45
  /** Custom stdout log file path */
46
  output?: string;
47
  
48
  /** Custom stderr log file path */
49
  error?: string;
50
  
51
  /** Log timestamp format (moment.js format) */
52
  log_date_format?: string;
53
  
54
  /** Custom PID file path */
55
  pid?: string;
56
  
57
  /** Enable auto restart on crash (default: true) */
58
  autorestart?: boolean;
59
  
60
  /** List of exit codes that should allow process to stop */
61
  stop_exit_codes?: number[];
62
  
63
  /** Minimum uptime before considering process stable */
64
  min_uptime?: number;
65
  
66
  /** Maximum restart attempts in unstable period */
67
  max_restarts?: number;
68
  
69
  /** Memory restart threshold (e.g., '150M', '1G') */
70
  max_memory_restart?: number | string;
71
  
72
  /** Node.js arguments (alias for interpreter_args) */
73
  node_args?: string | string[];
74
  
75
  /** Prefix logs with timestamp */
76
  time?: boolean;
77
  
78
  /** Wait for ready signal from process */
79
  wait_ready?: boolean;
80
  
81
  /** SIGKILL timeout in milliseconds (default: 1600) */
82
  kill_timeout?: number;
83
  
84
  /** Delay between restarts in milliseconds */
85
  restart_delay?: number;
86
  
87
  /** Script interpreter (default: 'node') */
88
  interpreter?: string;
89
  
90
  /** Force start even if process already running */
91
  force?: boolean;
92
  
93
  /** Cron pattern for scheduled restarts */
94
  cron?: string;
95
  
96
  /** Execute command instead of script */
97
  execute_command?: any;
98
  
99
  /** Write process output to files */
100
  write?: any;
101
  
102
  /** Enable source map support */
103
  source_map_support?: any;
104
  
105
  /** Disable source map support */
106
  disable_source_map_support?: any;
107
  
108
  /** Process namespace (default: 'default') */
109
  namespace?: string;
110
  
111
  /** Exponential backoff restart delay */
112
  exp_backoff_restart_delay?: number;
113
  
114
  /** Listen timeout for reload operations */
115
  listen_timeout?: number;
116
  
117
  /** Shutdown using message instead of SIGKILL */
118
  shutdown_with_message?: boolean;
119
  
120
  /** Environment variable name incremented for each instance */
121
  increment_var?: string;
122
  
123
  /** Instance ID environment variable name */
124
  instance_var?: string;
125
  
126
  /** Filter environment variables */
127
  filter_env?: boolean | string | string[];
128
  
129
  /** Disable log output */
130
  disable_logs?: boolean;
131
  
132
  /** Log output type */
133
  log_type?: string;
134
  
135
  /** Container mode for Docker */
136
  container?: boolean;
137
  
138
  /** Distribution mode for Docker */
139
  dist?: boolean;
140
  
141
  /** Docker image name */
142
  image_name?: string;
143
  
144
  /** Node.js version for Docker */
145
  node_version?: string;
146
  
147
  /** Fresh install for Docker */
148
  fresh?: boolean;
149
  
150
  /** Docker daemon mode */
151
  dockerdaemon?: boolean;
152
}
153
```
154

155
### ProcessDescription Interface
156

157
Complete process information structure returned by PM2.
158

159
```typescript { .api }
160
interface ProcessDescription {
161
  /** Process name as specified in configuration */
162
  name?: string;
163
  
164
  /** System process ID */
165
  pid?: number;
166
  
167
  /** PM2 internal process ID */
168
  pm_id?: number;
169
  
170
  /** Real-time monitoring data */
171
  monit?: Monit;
172
  
173
  /** PM2 environment and configuration data */
174
  pm2_env?: Pm2Env;
175
}
176
```
177

178
### Monitoring Interface
179

180
Real-time process monitoring data.
181

182
```typescript { .api }
183
interface Monit {
184
  /** Memory usage in bytes */
185
  memory?: number;
186
  
187
  /** CPU usage percentage (0-100) */
188
  cpu?: number;
189
}
190
```
191

192
### PM2 Environment Interface
193

194
Complete PM2 environment data for processes.
195

196
```typescript { .api }
197
interface Pm2Env {
198
  /** Process working directory */
199
  pm_cwd?: string;
200
  
201
  /** Stdout log file path */
202
  pm_out_log_path?: string;
203
  
204
  /** Stderr log file path */
205
  pm_err_log_path?: string;
206
  
207
  /** Script interpreter being used */
208
  exec_interpreter?: string;
209
  
210
  /** Process uptime in milliseconds */
211
  pm_uptime?: number;
212
  
213
  /** Number of unstable restarts */
214
  unstable_restarts?: number;
215
  
216
  /** Last restart timestamp */
217
  restart_time?: number;
218
  
219
  /** Current process status */
220
  status?: ProcessStatus;
221
  
222
  /** Number of instances running */
223
  instances?: number | 'max';
224
  
225
  /** Full path to executable script */
226
  pm_exec_path?: string;
227
}
228
```
229

230
## Process Management Interfaces
231

232
### Proc Interface
233

234
Basic process information returned by lifecycle operations.
235

236
```typescript { .api }
237
interface Proc {
238
  /** Process name */
239
  name?: string;
240
  
241
  /** Enable version control integration */
242
  vizion?: boolean;
243
  
244
  /** Auto restart on failure */
245
  autorestart?: boolean;
246
  
247
  /** Execution mode */
248
  exec_mode?: string;
249
  
250
  /** Script interpreter */
251
  exec_interpreter?: string;
252
  
253
  /** Executable path */
254
  pm_exec_path?: string;
255
  
256
  /** Working directory */
257
  pm_cwd?: string;
258
  
259
  /** Number of instances */
260
  instances?: number;
261
  
262
  /** Node.js arguments */
263
  node_args?: string[];
264
  
265
  /** Stdout log path */
266
  pm_out_log_path?: string;
267
  
268
  /** Stderr log path */
269
  pm_err_log_path?: string;
270
  
271
  /** PID file path */
272
  pm_pid_path?: string;
273
  
274
  /** Current status */
275
  status?: string;
276
  
277
  /** Process uptime */
278
  pm_uptime?: number;
279
  
280
  /** AXM actions available */
281
  axm_actions?: any[];
282
  
283
  /** AXM monitoring data */
284
  axm_monitor?: any;
285
  
286
  /** AXM dynamic data */
287
  axm_dynamic?: any;
288
  
289
  /** Version control running status */
290
  vizion_running?: boolean;
291
  
292
  /** Process creation timestamp */
293
  created_at?: number;
294
  
295
  /** PM2 process ID */
296
  pm_id?: number;
297
  
298
  /** Number of restarts */
299
  restart_time?: number;
300
  
301
  /** Unstable restart count */
302
  unstable_restarts?: number;
303
  
304
  /** Started inside PM2 flag */
305
  started_inside?: boolean;
306
  
307
  /** Command execution data */
308
  command?: Command;
309
  
310
  /** Version control information */
311
  versioning?: any;
312
  
313
  /** Process exit code */
314
  exit_code?: number;
315
}
316
```
317

318
### Command Interface
319

320
Command execution metadata.
321

322
```typescript { .api }
323
interface Command {
324
  /** Command locked status */
325
  locked?: boolean;
326
  
327
  /** Command metadata */
328
  metadata?: any;
329
  
330
  /** Command start timestamp */
331
  started_at?: any;
332
  
333
  /** Command completion timestamp */
334
  finished_at?: any;
335
  
336
  /** Command error information */
337
  error?: any;
338
}
339
```
340

341
### ReloadOptions Interface
342

343
Options for zero-downtime reload operations.
344

345
```typescript { .api }
346
interface ReloadOptions {
347
  /** Update environment variables from process.env before reloading */
348
  updateEnv?: boolean;
349
}
350
```
351

352
## Configuration Interfaces
353

354
### ServeOptions Interface
355

356
Options for static file serving functionality.
357

358
```typescript { .api }
359
interface ServeOptions {
360
  /** Single Page Application mode - serve index.html for all routes */
361
  spa?: boolean;
362
  
363
  /** Basic authentication username */
364
  basic_auth_username?: string;
365
  
366
  /** Basic authentication password */
367
  basic_auth_password?: string;
368
  
369
  /** Monitor URL path for health checks */
370
  monitor?: string;
371
}
372
```
373

374
### InstallOptions Interface
375

376
Options for PM2 module installation.
377

378
```typescript { .api }
379
interface InstallOptions {
380
  /** Install from tarball instead of npm */
381
  tarball?: boolean;
382
  
383
  /** Perform installation (default: true) */
384
  install?: boolean;
385
  
386
  /** Docker mode installation */
387
  docker?: boolean;
388
  
389
  /** Use PM2 v1 API compatibility */
390
  v1?: boolean;
391
  
392
  /** Safe mode installation with retry attempts */
393
  safe?: boolean | number;
394
}
395
```
396

397
### DockerOptions Interface
398

399
Options for Docker-related operations.
400

401
```typescript { .api }
402
interface DockerOptions {
403
  /** Docker image name for containerization */
404
  imageName?: string;
405
  
406
  /** Node.js version to use in container */
407
  nodeVersion?: string;
408
  
409
  /** Perform fresh installation in container */
410
  fresh?: boolean;
411
  
412
  /** Force Docker operations */
413
  force?: boolean;
414
  
415
  /** Docker daemon mode */
416
  dockerdaemon?: boolean;
417
}
418

419
/**
420
 * Options for module publishing
421
 */
422
export interface PublishOptions {
423
  /** Make module public in registry */
424
  public?: boolean;
425
  /** Force publish even if version exists */
426
  force?: boolean;
427
  /** Include development dependencies */
428
  dev?: boolean;
429
}
430

431
/**
432
 * Version control information
433
 */
434
export interface VersionInfo {
435
  /** Repository path */
436
  repo_path?: string;
437
  /** Current branch */
438
  branch?: string; 
439
  /** Current commit hash */
440
  revision?: string;
441
  /** Commit message */
442
  comment?: string;
443
  /** Last update timestamp */
444
  update_time?: number;
445
}
446

447
/**
448
 * Deployment configuration
449
 */
450
export interface DeploymentConfig {
451
  /** SSH user for deployment */
452
  user: string;
453
  /** Target host(s) for deployment */
454
  host: string | string[];
455
  /** Git reference to deploy (branch/tag) */
456
  ref: string;
457
  /** Git repository URL */
458
  repo: string;
459
  /** Deployment path on remote server */
460
  path: string;
461
  /** Commands to run before deployment */
462
  'pre-deploy'?: string;
463
  /** Commands to run after deployment */
464
  'post-deploy'?: string;
465
  /** Commands to run during initial setup */
466
  'pre-setup'?: string;
467
  /** Commands to run after initial setup */
468
  'post-setup'?: string;
469
}
470
```
471

472
## Type Definitions
473

474
### ProcessStatus Type
475

476
Enumeration of possible process statuses.
477

478
```typescript { .api }
479
type ProcessStatus = 
480
  | 'online'           // Process running normally
481
  | 'stopping'         // Process being stopped
482
  | 'stopped'          // Process stopped
483
  | 'launching'        // Process being started
484
  | 'errored'          // Process crashed/errored
485
  | 'one-launch-status' // One-time launch status
486
  | 'waiting_restart'; // Waiting for restart
487
```
488

489
### Platform Type
490

491
Supported platforms for startup script generation.
492

493
```typescript { .api }
494
type Platform = 
495
  | 'ubuntu'    // Ubuntu Linux
496
  | 'centos'    // CentOS Linux  
497
  | 'redhat'    // Red Hat Linux
498
  | 'gentoo'    // Gentoo Linux
499
  | 'systemd'   // systemd-based systems
500
  | 'darwin'    // macOS
501
  | 'amazon';   // Amazon Linux
502
```
503

504
## Callback Type Definitions
505

506
### Standard Callback Types
507

508
```typescript { .api }
509
/** Standard error callback */
510
type ErrCallback = (err: Error) => void;
511

512
/** Error callback with process data */
513
type ErrProcCallback = (err: Error, proc: Proc) => void;
514

515
/** Error callback with process description */
516
type ErrProcDescCallback = (err: Error, processDescription: ProcessDescription) => void;
517

518
/** Error callback with process description array */
519
type ErrProcDescsCallback = (err: Error, processDescriptionList: ProcessDescription[]) => void;
520

521
/** Error callback with generic result */
522
type ErrResultCallback = (err: Error, result: any) => void;
523

524
/** Error callback with message bus */
525
type ErrBusCallback = (err: Error, bus: any) => void;
526
```
527

528
## Function Signatures
529

530
### Main API Function Signatures
531

532
Complete function signatures for all PM2 API methods with proper TypeScript typing.
533

534
```typescript { .api }
535
// Connection Management
536
function connect(callback: ErrCallback): void;
537
function connect(noDaemonMode: boolean, callback: ErrCallback): void;
538
function disconnect(): void;
539

540
// Process Lifecycle
541
function start(options: StartOptions, callback: ErrProcCallback): void;
542
function start(script: string, callback: ErrProcCallback): void;
543
function start(script: string, options: StartOptions, callback: ErrProcCallback): void;
544
function start(jsonConfigFile: string, callback: ErrProcCallback): void;
545

546
function stop(process: string | number, callback: ErrProcCallback): void;
547
function restart(process: string | number, callback: ErrProcCallback): void;
548
function reload(process: string | number, callback: ErrProcCallback): void;
549
function reload(process: string | number, options: ReloadOptions, callback: ErrProcCallback): void;
550
function delete(process: string | number, callback: ErrProcCallback): void;
551

552
// Process Information
553
function list(callback: ErrProcDescsCallback): void;
554
function describe(process: string | number, callback: ErrProcDescsCallback): void;
555
function getPID(app_name?: string, callback?: ErrProcCallback): void;
556

557
// Configuration
558
function get(key?: string, callback?: ErrCallback): void;
559
function set(key: string, value: any, callback?: ErrCallback): void;
560
function multiset(values: string, callback?: ErrCallback): void;
561
function unset(key: string, callback?: ErrCallback): void;
562

563
// State Management
564
function dump(callback: ErrResultCallback): void;
565
function resurrect(callback: ErrResultCallback): void;
566

567
// Monitoring and Communication
568
function launchSysMonitoring(callback?: ErrCallback): void;
569
function launchBus(callback: ErrBusCallback): void;
570
function profile(type: 'cpu' | 'mem', time?: number, callback?: ErrCallback): void;
571
function sendDataToProcessId(proc_id: number, packet: object, callback: ErrResultCallback): void;
572
function sendLineToStdin(pm_id: string | number, line: string, separator?: string, callback?: ErrCallback): void;
573
function trigger(pm_id: string | number, action_name: string, params?: any, callback?: ErrCallback): void;
574
function sendSignalToProcessName(signal: string | number, process: number | string, callback: ErrResultCallback): void;
575

576
// System Integration
577
function startup(platform: Platform, callback: ErrResultCallback): void;
578
function killDaemon(callback: ErrProcDescCallback): void;
579

580
// Utilities
581
function serve(path?: string, port?: number, options?: ServeOptions, callback?: ErrCallback): void;
582
function install(module_name: string, options?: InstallOptions, callback?: ErrCallback): void;
583
function uninstall(module_name: string, callback?: ErrCallback): void;
584
function env(app_id: string | number, callback?: ErrCallback): void;
585
function inspect(app_name: string, callback?: ErrCallback): void;
586
function attach(pm_id: string | number, separator?: string, callback?: ErrCallback): void;
587
function flush(process: number | string, callback: ErrResultCallback): void;
588
function reloadLogs(callback: ErrResultCallback): void;
589

590
// State Persistence
591
function dump(callback: ErrResultCallback): void;
592
function resurrect(callback: ErrResultCallback): void;
593
function clearDump(callback: ErrResultCallback): void;
594
function autodump(callback: ErrResultCallback): void;
595

596
// Module Management  
597
function deleteModule(module_name: string, callback?: ErrCallback): void;
598
function generateModuleSample(app_name: string, callback?: ErrCallback): void;
599
function package(module_path: string, callback?: ErrCallback): void;
600
function publish(folder: string, options?: PublishOptions, callback?: ErrCallback): void;
601

602
// Version Control Integration
603
function pullAndRestart(process_name: string, callback?: ErrResultCallback): void;
604
function pullAndReload(process_name: string, callback?: ErrResultCallback): void; 
605
function pullCommitId(process_name: string, commit_id: string, callback?: ErrResultCallback): void;
606
function backward(process_name: string, callback?: ErrResultCallback): void;
607
function forward(process_name: string, callback?: ErrResultCallback): void;
608

609
// Docker Integration
610
function generateDockerfile(script: string, options?: DockerOptions): string;
611
function dockerMode(script: string, options?: DockerOptions, mode?: string): any;
612

613
// System Information
614
function getVersion(callback?: ErrCallback): void;
615
function report(): void;
616
function ping(callback?: ErrCallback): void;
617
function update(callback?: ErrCallback): void;
618

619
// Extended Signal Management
620
function sendSignalToProcessId(signal: string | number, process_id: number, callback: ErrResultCallback): void;
621
```
622

623
## Usage Examples with TypeScript
624

625
### Type-Safe Process Starting
626

627
```typescript
628
import * as pm2 from 'pm2';
629
import { StartOptions, ProcessDescription } from 'pm2';
630

631
const startOptions: StartOptions = {
632
  name: 'my-app',
633
  script: './app.js',
634
  instances: 'max' as any, // instances can be number or 'max'
635
  exec_mode: 'cluster',
636
  env: {
637
    NODE_ENV: 'production',
638
    PORT: '3000'
639
  },
640
  watch: true,
641
  ignore_watch: ['node_modules', 'logs'],
642
  max_memory_restart: '1G',
643
  autorestart: true,
644
  max_restarts: 5,
645
  min_uptime: 10000
646
};
647

648
pm2.connect((err: Error) => {
649
  if (err) {
650
    console.error('Connection error:', err);
651
    process.exit(2);
652
  }
653

654
  pm2.start(startOptions, (err: Error, proc) => {
655
    if (err) {
656
      console.error('Start error:', err);
657
      return pm2.disconnect();
658
    }
659
    
660
    console.log('Process started:', proc[0].name);
661
    pm2.disconnect();
662
  });
663
});
664
```
665

666
### Type-Safe Process Information
667

668
```typescript
669
pm2.list((err: Error, processes: ProcessDescription[]) => {
670
  if (err) throw err;
671
  
672
  processes.forEach((proc: ProcessDescription) => {
673
    console.log(`Process: ${proc.name}`);
674
    console.log(`  Status: ${proc.pm2_env?.status}`);
675
    console.log(`  Memory: ${proc.monit?.memory} bytes`);
676
    console.log(`  CPU: ${proc.monit?.cpu}%`);
677
    console.log(`  Uptime: ${proc.pm2_env?.pm_uptime}ms`);
678
  });
679
});
680
```
681

682
### Type-Safe Configuration
683

684
```typescript
685
import { ServeOptions } from 'pm2';
686

687
const serveOptions: ServeOptions = {
688
  spa: true,
689
  basic_auth_username: 'admin',
690
  basic_auth_password: 'secret',
691
  monitor: '/health'
692
};
693

694
pm2.serve('./public', 8080, serveOptions, (err: Error) => {
695
  if (err) throw err;
696
  console.log('Static server started with SPA support');
697
});
698
```
699

700
## Module Declaration
701

702
Complete module declaration for PM2 TypeScript support.
703

704
```typescript { .api }
705
declare module 'pm2' {
706
  // Export all interfaces and types
707
  export interface StartOptions { /* ... */ }
708
  export interface ProcessDescription { /* ... */ }
709
  export interface Monit { /* ... */ }
710
  export interface Pm2Env { /* ... */ }
711
  export interface Proc { /* ... */ }
712
  export interface Command { /* ... */ }
713
  export interface ReloadOptions { /* ... */ }
714
  export interface ServeOptions { /* ... */ }
715
  export interface InstallOptions { /* ... */ }
716
  export interface DockerOptions { /* ... */ }
717
  
718
  export type ProcessStatus = 'online' | 'stopping' | 'stopped' | 'launching' | 'errored' | 'one-launch-status' | 'waiting_restart';
719
  export type Platform = 'ubuntu' | 'centos' | 'redhat' | 'gentoo' | 'systemd' | 'darwin' | 'amazon';
720
  
721
  // Export all callback types
722
  export type ErrCallback = (err: Error) => void;
723
  export type ErrProcCallback = (err: Error, proc: Proc) => void;
724
  export type ErrProcDescCallback = (err: Error, processDescription: ProcessDescription) => void;
725
  export type ErrProcDescsCallback = (err: Error, processDescriptionList: ProcessDescription[]) => void;
726
  export type ErrResultCallback = (err: Error, result: any) => void;
727
  export type ErrBusCallback = (err: Error, bus: any) => void;
728
  
729
  // Export all API functions
730
  export function connect(callback: ErrCallback): void;
731
  export function connect(noDaemonMode: boolean, callback: ErrCallback): void;
732
  export function disconnect(): void;
733
  
734
  export function start(options: StartOptions, callback: ErrProcCallback): void;
735
  export function start(script: string, callback: ErrProcCallback): void;
736
  export function start(script: string, options: StartOptions, callback: ErrProcCallback): void;
737
  export function start(jsonConfigFile: string, callback: ErrProcCallback): void;
738
  
739
  // ... all other function exports
740
  
741
  // Custom API class export
742
  export const custom: any;
743
}
744
```