Metadata-Version: 2.4
Name: waitfor-cli
Version: 0.1.0
Summary: Wait for conditions (port, file, URL, process) in automation scripts
Author-email: Marcus <marcus.builds.things@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/marcusbuildsthings-droid/waitfor
Project-URL: Repository, https://github.com/marcusbuildsthings-droid/waitfor
Project-URL: Issues, https://github.com/marcusbuildsthings-droid/waitfor/issues
Keywords: cli,automation,wait,port,process,devops,scripting
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Dynamic: license-file

# waitfor

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

## Installation

```bash
pip install waitfor-cli
```

## Usage

### Wait for a port to be open

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Wait for process to start
waitfor process nginx

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

### Wait for a command to succeed

```bash
# 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

```bash
# 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

```bash
$ 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

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

### Deployment script

```bash
#!/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

```bash
# Start build in background
make build &

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

## For AI Agents

See [SKILL.md](SKILL.md) for agent-optimized documentation.

## License

MIT
