CLI Reference

procman <CONFIG> [OPTIONS] [-- ARGS]

Spawn all processes defined in the config file and wait for exit or signal.

• CONFIG is a required positional argument — the path to the .pman config file.
• Acquires an exclusive advisory lock on the config file to prevent concurrent instances.
• On SIGINT or SIGTERM, initiates graceful shutdown.

procman myapp.pman
procman myapp.pman -e PORT=3000 -e RUST_LOG=debug
procman myapp.pman --debug
procman myapp.pman --check                     # validate config and exit
procman myapp.pman -- --rust-log debug --verbose

-e / --env — Extra environment variables

A repeatable -e KEY=VALUE flag to inject environment variables without modifying the config file.

procman myapp.pman -e PORT=3000 -e RUST_LOG=debug

-t / --task — Trigger tasks

A repeatable -t NAME flag that activates one or more tasks by name. Tasks are one-shot processes defined with task blocks that don’t auto-start — they must be explicitly triggered via this flag.

procman myapp.pman -t migrate
procman myapp.pman -t test_a -t test_b

If a named task does not exist in the config, procman exits with an error and lists available tasks. A non-zero exit code from any task triggers shutdown of all processes.

-- [ARGS] — User-defined arguments

Arguments after -- are parsed according to the config.args definitions in the config file. See the Configuration chapter for how to define args.

procman myapp.pman -- --rust-log debug --enable-feature

Running -- --help prints generated usage based on the config.args definitions:

procman myapp.pman -- --help

This shows each defined argument’s name, type, description, default value, and short form.

--check — Validate config and exit

The --check flag runs the full config parse and validation pipeline — arg definitions, template resolution, dependency graph cycle detection, output reference validation, watch uniqueness, and all other static checks — then exits without starting any processes.

procman myapp.pman --check

On success, exits silently with code 0. On failure, prints the error and exits non-zero. Warnings (e.g. parameterized imports skipped because args are unbound) are printed in the standard file:line:col: warning: description format. This is useful for:

• Editor integration — run --check on save for instant feedback.
• CI pipelines — catch config errors before deployment.
• Quick validation — verify a config without spawning anything.

No signal handlers, loggers, or processes are created.

--debug — Pause before shutdown

The --debug flag pauses the shutdown sequence when a child process fails or a dependency times out, giving you time to inspect remaining processes before they are terminated.

procman myapp.pman --debug

When triggered, procman prints:

• Which process caused the shutdown (name, PID, exit code or signal)
• A list of processes still running (name and PID)
• A prompt to press ENTER (or Ctrl+C) to continue with the normal shutdown sequence

The --debug flag requires an interactive terminal (stdin must be a TTY). If stdin is not a TTY, procman exits immediately with an error.

Environment variable precedence

Precedence (lowest → highest):

Per-iteration for bindings win over per-job env, which wins over global config { env { } }, which wins over CLI -e flags, which win over inherited system environment variables.

File locking

Procman acquires an exclusive advisory lock (flock) on the config file before starting. If another procman instance is already running with the same config, the second instance exits immediately with an error message.

Exit code

Procman’s exit code is the exit code of the first process that terminated (the one that triggered shutdown). If the first termination was caused by a signal rather than a normal exit, the exit code is 1.

Signals

On SIGINT (Ctrl-C) or SIGTERM, procman initiates graceful shutdown: SIGTERM is sent to each child’s process group, followed by a 2-second grace period, then SIGKILL for any stragglers.