Documentation

womp is a local-dev process orchestrator. You describe your services in a single womp.yaml, and womp boots them in dependency order, waits for each to be genuinely healthy, supervises them, streams their logs, and tears everything down cleanly on exit.

Install

curl -fsSL https://raw.githubusercontent.com/idrissgarfa/womp/develop/install.sh | sh

The script detects your platform (macOS or Linux, Intel or ARM) and drops the womp binary in /usr/local/bin, falling back to ~/.local/bin if that is not writable. Set WOMP_INSTALL_DIR to install elsewhere, or WOMP_VERSION=v0.1.0 to pin a release. Prefer to do it by hand? Grab a tarball from the releases page and move womp onto your PATH.

Configuration

womp.yaml lives at your project root and is committed to version control. Everything lives under services:, keyed by service name.

services:
  db:
    cmd: "docker run --rm -p 5432:5432 postgres:16"
    health: { tcp: "localhost:5432", timeout: 30s }
  api:
    cmd: "uv run fastapi dev"
    dir: ./apps/api
    env: { DATABASE_URL: "postgres://localhost:5432/app" }
    depends_on: [db]
    health: { http: "http://localhost:8000/health", timeout: 20s }
    restart: { policy: on-failure, max: 3, backoff: 1s }
    watch: { paths: ["src/**"], debounce: 300ms }
  web:
    cmd: "bun dev"
    dir: ./apps/web
    depends_on: [api]
    health: { log: "ready in .*ms" }

Field	Meaning
`cmd`	Command to run (required), executed via `sh -c`.
`dir`	Working directory for the process.
`env`	Environment variables for the process.
`depends_on`	Services that must be healthy before this one starts.
`health`	One of `tcp`, `http`, or `log`, plus an optional `timeout`. No health block means healthy the instant it spawns.
`restart`	`policy`, `max` tries, and `backoff` base.
`watch`	Restart the service when files change.
`grace`	Wait after `SIGTERM` before `SIGKILL` on teardown (default `10s`).

Durations are written 300ms, 30s, or 2m. Unknown keys, a missing cmd, a dependency cycle, or a reference to a service that does not exist are all rejected up front with an error that names the exact service and field. Cycles print the path: cycle: api -> worker -> api.

Health probes

A service is STARTING until its probe passes, then HEALTHY. Dependents do not start until it is healthy.

Probe	Passes when
`tcp: "host:port"`	A TCP connection to the address succeeds.
`http: "url"`	A `GET` returns a 2xx status.
`log: "regex"`	A line matching the regex appears in the service’s output.

timeout (default 30s) bounds how long the probe may take before the service is marked unhealthy.

Restart

Key	Meaning
`policy`	`on-failure`, `always`, or `never`.
`max`	Restart attempts before the service goes `FAILED` (default `3`).
`backoff`	Base delay; doubles each attempt, capped at `30s`.

When a service exhausts its restarts it goes FAILED, and every service that transitively depends on it is marked DEGRADED with the root cause recorded (web DEGRADED (root cause: db failed after 3 restarts)). Degraded services are not killed.

Watch mode

Give a service a watch block and womp restarts it when matching files change, debounced so a burst of saves counts as one restart.

watch:
  paths: ["**/*.py"]        # globs, relative to the service dir
  debounce: 300ms           # quiet window before restarting
  ignore: ["migrations/**"] # extra patterns to never restart on
  default_ignores: true     # built-in ignore list (on by default)
  use_gitignore: true       # honor .gitignore / .ignore (on by default)

Build tools write files themselves on startup (dependency caches, build output, generated code), so a broad glob can trigger an endless restart loop. Before a changed path is matched against your paths, womp filters it through three layers: your repo’s .gitignore, a built-in list of never-source directories (node_modules, target, __pycache__, all dot-directories, and more), and a built-in list of generated-file globs (*.gen.ts, *.pb.go, *_pb2.py, *.g.dart) that catches codegen committed to git. Set default_ignores: false to match only what you write.

CLI

Command	What it does
`womp up [--tui]`	Boot the whole graph and supervise it. `--tui` opens the dashboard.
`womp status [--json]`	Print each service’s state once and exit.
`womp restart <service>`	Restart one service; its dependents re-check health.
`womp stop`	Tell a running womp to shut down (same as `Ctrl-C`).
`womp help`	Full reference, including interactive keys.

status, restart, and stop reach a running womp up over a Unix socket at .womp/control.sock. Kill womp with kill -9 and the next womp up notices the stale socket and recovers.

Plain womp up is non-interactive and pipe-friendly. Stop it with Ctrl-C; drive it with womp restart / womp stop from another terminal.

Exit codes

Code	Meaning
`0`	Success. For `status`, every service is healthy.
`1`	Runtime error: unreadable or invalid config, cannot bind the socket.
`2`	Usage error, unknown command, or `status` found an unhealthy service.

TUI keybindings

womp up --tui opens a full-screen dashboard: a service list on the left (state, uptime, restart count) and logs on the right. There is a focused pane, shown by a highlighted border.

Key	Action
`Tab`	Move focus between the services and logs panes.
`←` `→` `h` `l`	Focus the services / logs pane.
`↑` `↓` `j` `k`	Act on the focused pane: change service, or scroll logs.
mouse wheel	Scroll logs or change service, by the pane under the cursor.
`b` `Space`	Page the logs up / down.
`Ctrl-U` `Ctrl-D`	Half-page the logs up / down.
`g` `G`	Jump to top / bottom of the logs (`G` resumes follow).
`f`	Toggle follow (auto-scroll to newest).
`r`	Restart the selected service.
`q` `Esc` `Ctrl-C`	Quit (graceful teardown, same as `Ctrl-C`).