waitfor

Wait for conditions in automation scripts. Check for ports, files, URLs, or processes before continuing.

Installation

pip install waitfor-cli

Usage

Wait for a port to be open

# Wait for port 8080 on localhost
waitfor port 8080

# Wait for port on remote host
waitfor port 5432 -h db.example.com

# Wait for port to be CLOSED
waitfor port 8080 --closed

Wait for a file

# Wait for file to exist
waitfor file /tmp/ready.flag

# Wait for file to be gone
waitfor file /var/run/app.pid --gone

# Wait for file to contain specific content
waitfor file /var/log/app.log --contains "Server started"

Wait for a URL to respond

# Wait for health endpoint
waitfor url http://localhost:3000/health

# Wait for specific status code
waitfor url http://api.example.com/status --status 200

# Wait for response to contain string
waitfor url http://localhost:8080/ready --contains "ok"

Wait for a process

# Wait for process to start
waitfor process nginx

# Wait for process to stop
waitfor process nginx --gone

Wait for a command to succeed

# Wait for docker container to be healthy
waitfor command "docker inspect --format='{{.State.Health.Status}}' myapp | grep healthy"

# Wait for database to accept connections
waitfor command "pg_isready -h localhost"

Wait for remote TCP connection

# Wait for database to be reachable
waitfor tcp db.example.com 5432

# Wait for Redis
waitfor tcp localhost 6379

Options

All commands support these common options:

Exit Codes

• 0 - Condition met
• 1 - Timeout or condition not met

JSON Output

$ waitfor port 8080 --json
{"success": true, "condition": "port 8080 on localhost to be open", "elapsed_seconds": 0.01, "attempts": 1}

Examples

Wait for services before running tests

#!/bin/bash
waitfor port 5432 -t 60 && \
waitfor port 6379 -t 30 && \
waitfor url http://localhost:8080/health -t 60 && \
pytest

Deployment script

#!/bin/bash
docker-compose up -d

# Wait for all services
waitfor port 80 -t 120
waitfor url http://localhost/api/health --contains "healthy" -t 60

echo "Deployment complete!"

Wait for build artifact

# Start build in background
make build &

# Wait for output
waitfor file ./dist/app.js -t 300

For AI Agents

See SKILL.md for agent-optimized documentation.

License

MIT