prwr

Process Wrangler, or prwr, is a small process supervisor for local development.

It runs the commands your project needs, keeps their output in one terminal, and gives each line a stable colored label. It is built for Windows first, with no tmux, panes, curses, or TUI.

backend | started pid=12644
web     | started pid=18408
backend | Ready on http://localhost:8787
web     | VITE v7 ready in 420 ms

Install

npm install -g @puckzxz/prwr

Then add a .prwr.yml file to a project and run prwr from that project directory.

Quick Start

processes:
  backend:
    command: npm run dev:backend
    restart: on-failure

  web:
    command: npm run dev:web
    stdin: true
    env:
      PORT: "3000"

  docs:
    command: npm run dev
    cwd: ./docs

Start everything:

prwr

From another terminal in the same folder:

prwr status
prwr restart backend
prwr send web rs
prwr stop docs
prwr start docs
prwr down
prwr check

Config Files

prwr looks for config in this order:

1. .prwr.yml
2. .prwr.yaml
3. Procfile.dev
4. Procfile

You can also pass a config path directly:

prwr .\.prwr.yml
prwr .\Procfile.dev
prwr up --config .\.prwr.yml
prwr up --procfile .\Procfile.dev

Runtime state is stored in .prwr/supervisor.json inside the project. That file is how status, restart, stop, start, and down find the running supervisor.

Process Options

processes:
  backend:
    command: npm run dev
    cwd: ./apps/backend
    env:
      PORT: "3001"
    restart: manual
    killOnExit: false
    stdin: false
    startupDelayMs: 0
    restartBackoffMs: 0
    restartBackoffMaxMs: 0
    restartBackoffResetMs: 0
    restartMaxAttempts: 0

• command: command to run. Required.
• cwd: working directory, resolved relative to the config file.
• env: environment values merged with the parent process.
• restart: manual, always, or on-failure. Defaults to manual.
• killOnExit: when true, this process exiting stops the whole supervisor.
• stdin: when true, enables prwr send <name> <text> for this process.
• startupDelayMs: delay before starting the process.
• restartBackoffMs: first automatic restart delay. Defaults to the existing Math.max(100, startupDelayMs) behavior when unset.
• restartBackoffMaxMs: maximum automatic restart delay. Defaults to no extra backoff cap when unset.
• restartBackoffResetMs: stable run time before automatic restart attempts reset. Defaults to disabled.
• restartMaxAttempts: maximum consecutive automatic restart attempts. 0 means unlimited.

Procfile Support

Simple Foreman-style Procfiles work too:

backend: npm run dev:backend
web: npm run dev:web
docs: npm run dev

Procfile commands run from the Procfile directory and use manual restart behavior.

Command Reference

| Command | What it does | | --- | --- | | prwr | Start the project using the first matching config file. | | prwr up | Same as prwr. | | prwr check | Validate config, resolved working directories, and supervisor state without starting processes. | | prwr status | Show supervisor and process state. | | prwr restart <name> | Kill one process tree and start it again. | | prwr stop <name> | Stop one process. | | prwr start <name> | Start one stopped process. | | prwr send <name> <text> | Send one newline-terminated input command to a process with stdin: true. | | prwr down | Stop every process tree and exit the supervisor. |

Windows Behavior

Windows is the main target. When prwr stops a process, it kills the whole tree:

taskkill /PID <pid> /T /F

That matters for commands like npm run dev, where the process you see first is often not the server doing the real work. prwr down, Ctrl+C, and prwr restart <name> all use the same tree-kill path.

On macOS and Linux, prwr starts processes in their own process groups where possible and stops the group with POSIX signals.

Output And Color

prwr colors the label and separator by default. Child output is passed through unchanged.

Use --no-color or NO_COLOR=1 to turn label colors off:

prwr --no-color

--no-color only controls prwr labels. Child commands still decide their own color output, and prwr preserves the existing default of setting FORCE_COLOR=1 unless it is already set.

Use --timestamps to prefix each log line with local time:

prwr --timestamps
prwr up --timestamps

14:32:07 backend | Ready on http://localhost:8787

Local Development

pnpm install
pnpm run build
pnpm test
node dist/cli.js --help

Release Process

Releases are published as @puckzxz/prwr on npm.

For the next release:

1. Update the version in package.json.
2. Run pnpm run lint, pnpm run build, pnpm test, and pnpm run pack:check.
3. Commit the version change.
4. Push the commit and wait for CI to pass.
5. Publish from a local terminal with npm publish --access public.
6. Tag the commit with the same version, for example git tag -a v0.1.1 -m "v0.1.1".
7. Push the tag and create a GitHub release.

CI runs on pushes and tags. npm publishing is intentionally manual for now.

Limitations

• Child stdin is ignored unless stdin: true is set. prwr send is one-shot command input, not an interactive terminal.
• Child color output depends on the child tool.
• Windows stops use taskkill /F, so shutdown is forceful by design.