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.

完整安装指南与集成提示词将在购买后解锁。

Elastic APM Node.js Agent for Observability

Automation, Utilities & Developer Tools

免费