watchctl

Process supervisor with wait, watch, and retry phases.

Overview

watchctl runs a command through three optional phases:

1. Wait Phase - Block until dependencies are ready (TCP ports, HTTP endpoints, files exist)
2. Watch Phase - Run the command while monitoring health; terminate if checks fail
3. Retry Phase - Automatically restart failed commands with configurable backoff

If the wait phase times out, watchctl exits without starting the command. If a health check fails during watch phase, the process is terminated without retry.

Installation

Requires Rust 1.85+ (edition 2024).

From source

cargo install --path .

From releases

Download the appropriate binary from releases.

Quick Start

Wait for a database, then run your app with automatic restart:

watchctl \
  --wait-tcp db:5432 \
  --retry-times 3 \
  -- ./my-app

Usage

watchctl [OPTIONS] -- <COMMAND> [ARGS...]

Wait Phase

Wait for conditions before starting the command. HTTPS URLs are supported.

# Wait for TCP port
watchctl --wait-tcp localhost:5432 -- ./my-app

# Wait for HTTP endpoint
watchctl --wait-http http://localhost:8080/health -- ./my-app

# Wait for file
watchctl --wait-file /var/run/ready -- ./my-app

# Wait with delay
watchctl --wait-delay 5s -- ./my-app

# Combine conditions (all must pass)
watchctl --wait-tcp localhost:5432 --wait-http http://localhost:8080/health -- ./my-app

Watch Phase

Monitor health while running. HTTPS URLs are supported. --watch-delay delays only the first health probe; --watch-timeout still starts counting from process launch.

# Watch HTTP endpoint
watchctl --watch-http http://localhost:8080/health --watch-http-interval 30s -- ./my-app

# Wait 5s before the first watch probe
watchctl --watch-http http://localhost:8080/health --watch-delay 5s -- ./my-app

# Watch TCP port
watchctl --watch-tcp localhost:8080 -- ./my-app

# Watch file existence
watchctl --watch-file /var/run/healthy -- ./my-app

# Set maximum runtime
watchctl --watch-timeout 1h -- ./my-app

Retry Phase

Restart on failure:

# Retry up to 3 times
watchctl --retry-times 3 -- ./my-app

# Retry with delay
watchctl --retry-times 3 --retry-delay 5s -- ./my-app

# Retry with exponential backoff
watchctl --retry-times 5 --retry-delay 1s --retry-backoff -- ./my-app

# Retry only on specific exit codes
watchctl --retry-times 3 --retry-if 1,2,3 -- ./my-app

# Retry on any failure except permanent errors
watchctl --retry-times 3 --retry-except 78,77 -- ./my-app

# Re-run wait phase before each retry
watchctl --retry-times 3 --retry-with-wait --wait-tcp localhost:5432 -- ./my-app

Logging

By default, watchctl produces no output (clean stdio passthrough). Use --log to write watchctl messages to a file:

watchctl --log /var/log/watchctl.log --wait-tcp localhost:5432 -- ./my-app

The log level can be controlled via the RUST_LOG environment variable:

RUST_LOG=debug watchctl --log /var/log/watchctl.log -- ./my-app

Options

Options marked with * can be specified multiple times.

Wait Phase

Watch Phase

Retry Phase

General

Exit Codes

Duration Format

Durations support these suffixes:

• ms - milliseconds (e.g., 500ms)
• s - seconds (e.g., 30s)
• m - minutes (e.g., 5m)
• h - hours (e.g., 1h)

Compound durations (e.g., 1h30m) are not supported.

Examples

Wait for PostgreSQL before starting app

watchctl --wait-tcp localhost:5432 --wait-timeout 60s -- ./my-app

Supervised service with health checks

watchctl \
  --wait-tcp localhost:5432 \
  --watch-http http://localhost:8080/health \
  --watch-delay 5s \
  --watch-http-interval 30s \
  --retry-times 5 \
  --retry-delay 5s \
  --retry-backoff \
  --log /var/log/watchctl.log \
  -- ./my-service

Docker entrypoint

ENTRYPOINT ["watchctl", "--wait-tcp", "db:5432", "--"]
CMD ["./app"]

License

License The MIT License Copyright (c) 2026 Ivan Zakharchanka