aux4/poller

A versatile CLI polling utility for aux4 that repeatedly executes commands until they meet success conditions, fail criteria, or timeout.

Key Features:

• Poll any shell command until output matches expectations
• Pattern matching with wildcards (*DONE*) and alternation (READY|COMPLETE)
• Configurable intervals and timeouts
• Fail-fast detection
• Integration with aux4 workflows

Installation

aux4 aux4 pkger install aux4/poller

Quick Start

Wait for a service to be ready:

aux4 poll --command="curl -s http://localhost:8080/health" --expectation="OK" --maxWait=60 --interval=5

This polls every 5 seconds for up to 60 seconds, exiting successfully when the health endpoint returns "OK".

Simple example:

aux4 poll --command="echo READY" --expectation="READY" --maxWait=10 --interval=2

Output:

[0 s] READY
Complete

Use Cases

• Service health checks - Wait for services to become healthy before deploying
• Deployment monitoring - Poll deployment status until complete
• File watching - Monitor files or directories for specific content
• CI/CD pipelines - Wait for build artifacts or test results
• Database migrations - Check migration status before proceeding
• Container readiness - Ensure containers are ready before integration tests

Command Reference

Parameters

| Parameter | Description | Default | Required | | ------------- | ----------------------------------------------------------------- | ----------------- | -------- | | command | Shell command to execute on each poll | - | Yes | | expectation | Success pattern (exact, wildcard *DONE*, or alternation A\|B) | - | Yes | | failValue | Pattern indicating immediate failure | __NEVER_MATCH__ | No | | maxWait | Maximum wait time in seconds | 900 | No | | interval | Polling interval in seconds | 30 | No |

Output Format

Each poll prints:

[elapsed_seconds s] command_output

Terminal states print one of: Complete, Failed, or Timeout

For full command documentation see aux4 poll.

Pattern Matching

The expectation parameter supports flexible pattern matching:

Exact match:

aux4 poll --command="echo READY" --expectation="READY"

Wildcard match: Use * to match substrings

aux4 poll --command="echo STATUS_DONE" --expectation="*DONE*"

Alternation: Use | to match multiple alternatives

aux4 poll --command="echo TERMINATED" --expectation="TERMINATED|SKIPPED"

Fail Detection

Set failValue to exit immediately when a failure condition is detected:

aux4 poll --command="kubectl get pod my-pod -o jsonpath='{.status.phase}'" \
  --expectation="Running" \
  --failValue="Failed|Error" \
  --maxWait=300 --interval=5

Exit code 1 is returned when the fail value is matched.

Timeouts and Errors

Timeout: If expectation is not met within maxWait seconds, the command prints Timeout and exits with code 1.

Command errors: If the polled command fails (non-existent command, permission denied, etc.), ERROR is printed for that poll and polling continues until a terminal condition is reached.

Examples

Wait for HTTP endpoint

aux4 poll \
  --command="curl -s http://localhost:8080/health" \
  --expectation="healthy" \
  --maxWait=120 --interval=5

Wait for Kubernetes pod

aux4 poll \
  --command="kubectl get pod my-app -o jsonpath='{.status.phase}'" \
  --expectation="Running" \
  --failValue="Failed|Error" \
  --maxWait=300 --interval=10

Wait for file to contain specific text

aux4 poll \
  --command="cat /var/log/app.log" \
  --expectation="*Server started*" \
  --maxWait=60 --interval=2

Poll with changing status (file-based)

STATUS_FILE="/tmp/poll_status_$$"
echo "WAITING" | tee "$STATUS_FILE" > /dev/null
(sleep 3 && echo "READY" | tee "$STATUS_FILE" > /dev/null) &
aux4 poll --command="cat $STATUS_FILE" --expectation="READY" --maxWait=10 --interval=1
rm -f "$STATUS_FILE"

Output:

[0 s] WAITING
[1 s] WAITING
[2 s] WAITING
[3 s] READY
Complete

Wait for Docker container

aux4 poll \
  --command="docker inspect -f '{{.State.Health.Status}}' my-container" \
  --expectation="healthy" \
  --failValue="unhealthy" \
  --maxWait=180 --interval=10

Exit Codes

| Exit Code | Meaning | | --------- | ---------------------------------------------- | | 0 | Success - expectation matched | | 1 | Failure - timeout reached or failValue matched |

License

This package is licensed under the Apache License, Version 2.0.

See LICENSE for details.