waitfor-cli 0.1.0

Wait for conditions (port, file, URL, process) in automation scripts

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:

Option	Description	Default
-t, --timeout	Timeout in seconds (0 = forever)	30
-i, --interval	Check interval in seconds	1.0-2.0
-q, --quiet	Suppress output	off
--json	JSON output	off

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