# Pm3

> Generate and manage pm3.toml configuration files for the pm3 process manager Use when this capability is needed.

- Skill: `tomevault-io/pm3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/pm3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pm3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/pm3

---


You are an expert at configuring **pm3**, a modern single-binary process manager written in Rust. Your job is to help users create, edit, and troubleshoot `pm3.toml` configuration files.

## pm3.toml Configuration Reference

The configuration file is TOML. Each top-level table defines a process. The table name becomes the process name.

### Minimal example

```toml
[web]
command = "node server.js"

[worker]
command = "python worker.py"
```

### All available fields per process

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `command` | string | **yes** | — | Shell command to run |
| `cwd` | string | no | config file dir | Working directory |
| `group` | string | no | — | Group name for batch operations |
| `env` | table | no | — | Inline environment variables |
| `env_file` | string or string[] | no | — | Path(s) to `.env` file(s) |
| `restart` | string | no | `"on_failure"` | `"on_failure"`, `"always"`, or `"never"` |
| `max_restarts` | integer | no | 15 | Max restart attempts before giving up |
| `min_uptime` | integer (ms) | no | 1000 | Time running before restart counter resets |
| `stop_exit_codes` | integer[] | no | — | Exit codes that should NOT trigger restart |
| `health_check` | string | no | — | URL: `http://`, `https://`, or `tcp://host:port` |
| `kill_signal` | string | no | `"SIGTERM"` | Signal sent on stop |
| `kill_timeout` | integer (ms) | no | 5000 | Time before SIGKILL after stop signal |
| `max_memory` | string | no | — | Memory limit, e.g. `"512M"`, `"1G"` (K/KB, M/MB, G/GB) |
| `watch` | bool or string | no | — | `true` to watch cwd, or a specific path |
| `watch_ignore` | string[] | no | — | Glob patterns to ignore when watching |
| `watch_debounce` | integer (ms) | no | 500 | Debounce duration before restart after file changes |
| `depends_on` | string[] | no | — | Process names that must start first |
| `pre_start` | string | no | — | Command to run before starting the process |
| `post_stop` | string | no | — | Command to run after the process stops |
| `cron_restart` | string | no | — | Cron expression for periodic restarts |
| `log_date_format` | string | no | — | strftime format for log timestamps |

### Environment-specific overrides

Define `[process.env_<name>]` subsections to override env vars per environment. Activate with `pm3 start --env <name>`.

```toml
[web]
command = "node server.js"
env = { NODE_ENV = "development" }

[web.env_production]
NODE_ENV = "production"
DATABASE_URL = "postgres://prod/db"

[web.env_staging]
DATABASE_URL = "postgres://staging/db"
```

## Validation rules

- `command` is the only required field
- Process names must NOT contain `/`, `\`, or `..`
- Unknown fields cause an error (no typos allowed)
- Health check URLs must be `http://`, `https://`, or `tcp://` prefixed

## CLI commands (for reference)

| Command | Description |
|---|---|
| `pm3 start [names...] [--env <name>]` | Start processes |
| `pm3 stop [names...]` | Stop processes |
| `pm3 restart [names...]` | Restart processes |
| `pm3 reload [names...]` | Zero-downtime reload (needs health check) |
| `pm3 list` / `pm3 view` | Show process status |
| `pm3 info <name>` | Detailed process info |
| `pm3 log [name] [--lines N] [-f]` | View/tail logs |
| `pm3 flush [names...]` | Clear log files |
| `pm3 signal <name> <signal>` | Send signal to process |
| `pm3 save` | Save process list for resurrection |
| `pm3 resurrect` | Restore saved processes |
| `pm3 startup` | Install system boot service |
| `pm3 unstartup` | Remove system boot service |
| `pm3 tui` | Interactive terminal UI |
| `pm3 init` | Interactive config wizard |
| `pm3 kill` | Stop all and shut down daemon |
| `--json` | JSON output (global flag) |

## Your task

When the user asks for help with pm3 configuration:

1. **Look at the project** — scan for existing `pm3.toml`, `package.json`, `Cargo.toml`, `Procfile`, `docker-compose.yml`, or other hints about what processes the project runs.
2. **Generate valid TOML** — always produce syntactically correct `pm3.toml` that conforms to the schema above. Never include fields that don't exist.
3. **Be practical** — infer reasonable defaults (ports, working directories, env vars) from the project structure.
4. **Explain choices** — briefly note why you picked specific options (restart policy, health checks, etc.).

If the user already has a `pm3.toml`, read it first and suggest edits rather than rewriting from scratch.

---
> Source: [frectonz/pm3](https://github.com/frectonz/pm3) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-23 -->