Required dependencies

npm install @pm2/agent @pm2/blessed @pm2/io @pm2/js-api @pm2/pm2-version-check \
  ansis async chokidar cli-tableau commander croner dayjs debug enquirer \
  eventemitter2 fclone js-yaml mkdirp needle pidusage \
  pm2-axon pm2-axon-rpc pm2-deploy pm2-multimeter promptly semver

No native build steps, pod installs, or prebuild commands are required. All dependencies are pure JS or ship prebuilt binaries via npm optional dependencies. Node.js >= 12.x or Bun >= 1.x is required at runtime.

Project setup

1. Copy the source/ directory into your project, e.g. src/pm2-lib/. Also copy constants.js and paths.js from the upstream package root — the library requires both at ../constants.js and ../paths.js relative to source/.
2. Install all dependencies listed above into your project's package.json.
3. If using TypeScript, add a path alias in tsconfig.json:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": { "pm2-lib/*": ["src/pm2-lib/*"] }
     }
   }
   

4. The library is CommonJS (require). In an ESM project use dynamic import() or set "esm": false in your bundler config for this subtree.
5. Set environment variables as needed:

   PM2_HOME=~/.pm2            # daemon socket/log/pid directory (default)
   PM2_SECRET_KEY=...         # optional PM2 Plus secret key
   PM2_PUBLIC_KEY=...         # optional PM2 Plus public key
   PM2_MACHINE_NAME=...       # optional PM2 Plus instance label
   NODE_ENV=production
   

6. Require the API class from API.js — it is the sole public entry point for programmatic use.

Public API

API (constructor)

class API {
  constructor(opts?: {
    cwd?: string;
    pm2_home?: string;
    independent?: boolean;
    daemon_mode?: boolean;
    public_key?: string | null;
    secret_key?: string | null;
    machine_name?: string | null;
  });
  connect(noDaemonMode: boolean | ((err: Error, meta: object) => void), cb?: (err: Error, meta: object) => void): void;
  disconnect(): void;
  start(script: string | object, opts: object, cb?: (err: Error, proc: object) => void): void;
  stop(name: string | number, cb?: (err: Error, proc: object) => void): void;
  restart(name: string | number, opts: object, cb?: (err: Error, proc: object) => void): void;
  delete(name: string | number, cb?: (err: Error, proc: object) => void): void;
  list(cb: (err: Error, list: object[]) => void): void;
  describe(name: string | number, cb: (err: Error, list: object[]) => void): void;
}

The main class to instantiate. Call connect() before any process operation and disconnect() when done to release the RPC socket. Set daemon_mode: false to run everything in the same process (useful for tests).

CLI.prototype.install

function install(
  module_name: string,
  opts: object,
  cb?: (err: Error | null, data: any) => void
): void;

Installs or updates a PM2 module by name. Delegates to Modularizer.install. If no callback is supplied the process list is printed and the CLI exits with success or error code — pass a callback when using programmatically.

CLI.prototype.uninstall

function uninstall(
  module_name: string,
  cb?: (err: Error | null, data: any) => void
): void;

Removes a previously installed PM2 module. Delegates to Modularizer.uninstall. Safe to call at runtime; the module process is stopped before removal.

Client (constructor)

class Client {
  constructor(opts?: {
    conf?: object;
    daemon_mode?: boolean;
    secret_key?: string;
    public_key?: string;
    machine_name?: string;
  });
  start(cb: (err: Error | null, meta: object) => void): void;
  pingDaemon(cb: (alive: boolean) => void): void;
  launchRPC(cb: (err: Error | null, meta: object) => void): void;
  disconnectRPC(cb?: () => void): void;
}

Low-level RPC client. Prefer using API in application code. Use Client directly only when building tooling that needs raw daemon communication without the full CLI layer.

Working examples

Scenario - Start and list processes programmatically

Connect to a running PM2 daemon (or spawn one), start a script, list all processes, then cleanly disconnect.

const API = require('./src/pm2-lib/API.js');

const pm2 = new API({ daemon_mode: true });

pm2.connect(false, (err) => {
  if (err) { console.error(err); process.exit(1); }

  pm2.start('./worker.js', { name: 'my-worker', instances: 2, exec_mode: 'cluster' }, (startErr) => {
    if (startErr) console.error('start error', startErr);

    pm2.list((listErr, list) => {
      if (listErr) console.error(listErr);
      else console.log('running processes:', list.map((p: any) => p.name));

      pm2.disconnect();
    });
  });
});

Scenario - Install a PM2 module at runtime

Use the install method exposed on the API class (which mixes in API/Modules/index.js) to add a module such as pm2-logrotate without shelling out.

const API = require('./src/pm2-lib/API.js');

const pm2 = new API();

pm2.connect((err) => {
  if (err) throw err;

  (pm2 as any).install('pm2-logrotate', { safe: true }, (installErr: Error | null) => {
    if (installErr) console.error('install failed', installErr);
    else console.log('pm2-logrotate installed successfully');
    pm2.disconnect();
  });
});

Scenario - Embed PM2 in a self-contained test harness (no-daemon mode)

Run processes inside the current process without spawning a separate daemon — useful for integration tests.

const API = require('./src/pm2-lib/API.js');

async function runTest() {
  const pm2 = new API({ daemon_mode: false, independent: true });

  await new Promise<void>((res, rej) =>
    pm2.connect(false, (err) => (err ? rej(err) : res()))
  );

  await new Promise<void>((res, rej) =>
    pm2.start('./echo-server.js', { name: 'echo', env: { PORT: '4000' } },
      (err) => (err ? rej(err) : res()))
  );

  const list: any[] = await new Promise((res, rej) =>
    pm2.list((err, l) => (err ? rej(err) : res(l)))
  );
  console.assert(list.some((p) => p.name === 'echo'), 'process not found');

  pm2.disconnect();
}

runTest().catch(console.error);

File walkthrough

• API.js - Defines the API class; mixes in all sub-modules from API/; the sole programmatic entry point.
• Client.js - Manages axon RPC/PUB socket connections to the PM2 daemon; handles daemon ping and launch.
• Common.js - Process config normalisation, interpreter detection, error/log formatting shared across CLI and API layers.
• Configuration.js - Persistent key-value store backed by a JSON file in PM2_HOME; used by pm2 set/get/unset.
• Daemon.js - Forks and manages the God daemon process; handles signals and graceful shutdown.
• God.js / God/ - The supervisor core: ForkMode.js, ClusterMode.js, ActionMethods.js, Methods.js, Reload.js.
• API/Modules/ - install, uninstall, launchAll, package — npm and tarball module lifecycle.
• API/UX/ - list, describe, list_min, helpers — blessed/tableau terminal rendering.
• API/pm2-plus/ - PM2 Plus (Keymetrics) link/unlink, web and CLI auth strategies.
• API/Log.js / LogManagement.js - Real-time log streaming and flush/reopen operations.
• API/Startup.js - Generates and installs init scripts for systemd, upstart, launchd, etc.
• binaries/CLI.js - Commander-based CLI wiring; delegates to API.
• binaries/Runtime.js / Runtime4Docker.js - Drop-in node replacement for container use.
• ProcessContainer.js* - Per-process wrapper loaded inside each child; sets up IPC, @pm2/io, and graceful shutdown.
• ProcessUtils.js - Argument parsing and environment variable preparation before spawn.
• Watcher.js - Chokidar integration; emits restart events on file changes.
• Worker.js - Periodic croner tasks running inside the daemon (log rotation triggers, version checks).
• Event.js - Internal EventEmitter2 bus connecting daemon events to RPC subscribers.
• TreeKill.js - Recursively kills a process tree on any platform.
• Utility.js - Deep merge, byte formatting, random token generation.
• HttpInterface.js - Optional HTTP/JSON endpoint served by the daemon.
• VersionCheck.js - Asynchronously polls npm for newer PM2 versions.
• tools/ - Internal: Config (JSON store), sexec (shell exec), which, isbinaryfile.
• templates/ - Init script templates and sample application skeletons; not required at runtime.

Common pitfalls and fixes

• Cannot find module '../constants.js' - The library expects constants.js and paths.js one directory above source/; copy them from the upstream package root alongside source/.
• PM2_HOME collisions in tests - Multiple test processes sharing the same PM2_HOME corrupt the socket; set independent: true or point each instance to a unique temp directory via pm2_home.
• ESM project fails to require the library - All files use CommonJS module.exports; use createRequire from module or set "type": "commonjs" for this subtree.
• daemon_mode: false hangs - No-daemon mode still forks child processes; ensure process.exit() is called or all started apps are deleted before test teardown.
• ansis import errors - The upstream uses ansis not chalk; do not alias or mock chalk — install ansis directly.
• @pm2/agent peer mismatch - @pm2/agent must match the version range in pm2's own package.json; mismatches cause InteractorClient RPC failures silently at connect time.

Vibe-coding prompt template

I have dropped the PM2 core library source into `src/pm2-lib/` in my Node.js
project (upstream package: user@example.com, source from the `lib/` directory).
I also have `constants.js` and `paths.js` from the pm2 package root placed at
`src/constants.js` and `src/paths.js` respectively.
All runtime dependencies from USAGE.md are installed.

Please help me integrate this library step-by-step into my project:

1. Read `src/pm2-lib/API.js` and `src/pm2-lib/Client.js` to understand the
   public API surface.
2. Read `USAGE.md` in full for import paths, constructor options, and working
   examples.
3. Create a `ProcessManager` service class in `src/services/ProcessManager.ts`
   that wraps `API` with async/await helpers for: connect, start, stop,
   restart, list, describe, and disconnect.
4. Add error handling that surfaces pm2 daemon errors as typed exceptions.
5. Wire `ProcessManager` into my existing Express app at
   `src/app.ts` with graceful shutdown on SIGTERM.
6. Do not invent any API methods — only use symbols visible in API.js,
   Client.js, and API/Modules/index.js as documented in USAGE.md.

License and credit

PM2 is released under the GNU AGPL v3.0 license (see source/LICENSE if present in your copy, or the upstream repository at https://github.com/Unitech/pm2). The upstream npm package is pm2, authored by the PM2 project authors. Commercial use in a closed-source SaaS may require a separate license — consult the upstream repository.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Elastic APM Node.js Agent for Observability

Automation, Utilities & Developer Tools

Free