CLI Reference

Procman provides four subcommands. If no subcommand is given, run is used by default.

procman run [CONFIG]

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

• CONFIG defaults to procman.yaml.
• Acquires an exclusive advisory lock on the config file to prevent concurrent instances.
• On SIGINT or SIGTERM, initiates graceful shutdown.

procman run                 # uses procman.yaml
procman run services.yaml   # uses a custom config
procman run -e PORT=3000 -e RUST_LOG=debug

procman serve [CONFIG]

Like run, but also listens on a FIFO for dynamically added processes. See the Dynamic Process Management chapter for details.

• CONFIG defaults to procman.yaml.
• The FIFO path is auto-derived from the config path (deterministic, based on the parent directory name and a path hash).
• Also acquires an exclusive advisory lock on the config file.

procman serve &
procman serve -e PORT=3000

procman start COMMAND [--config CONFIG]

Send a run command to a running procman serve instance.

• COMMAND is the full command line to run. The process name is derived from the program basename (e.g. "redis-server --port 6380" runs as redis-server).
• –config defaults to procman.yaml and is used to derive the FIFO path.
• Fails immediately with a clear error if no server is listening (uses O_NONBLOCK).

procman start "redis-server --port 6380"
procman start "worker --threads 4" --config services.yaml
procman start "my-worker" -e DB_URL=postgres://localhost/mydb

procman stop [CONFIG]

Send a shutdown command to a running procman serve instance.

• CONFIG defaults to procman.yaml.
• Fails immediately if no server is listening.

procman stop

-e / --env — Extra environment variables

The run, serve, and start subcommands accept a repeatable -e KEY=VALUE flag to inject environment variables without modifying procman.yaml.

procman run -e PORT=3000 -e RUST_LOG=debug
procman start "my-worker" -e DB_URL=postgres://localhost/mydb

Precedence (lowest → highest):

For run and serve, YAML env: values always win over -e flags, which in turn override inherited system environment variables.

For start, the -e flags are sent to the server as part of the JSON message and merged on top of the server’s system environment.

--debug — Pause before shutdown

The run and serve subcommands accept a --debug flag that 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 run --debug
procman serve --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.

File locking

Both run and serve acquire 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.