pm3 - SKILL.md Agent Skill

name: pm3 description: Generate and manage pm3.toml configuration files for the pm3 process manager user-invocable: true allowed-tools: Read, Grep, Glob, Write, Edit, Bash

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

[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>.

[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:

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.
Generate valid TOML — always produce syntactically correct pm3.toml that conforms to the schema above. Never include fields that don't exist.
Be practical — infer reasonable defaults (ports, working directories, env vars) from the project structure.
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.