Interactive CLI Command Generator
Configure parameters below to generate your tailored Loopster command
loopster \
--test "curl -fsS http://localhost:8080/healthz" \
--loop "echo "Waiting for service container to be ready..."" \
--count 20 \
--wait 3 \
--success-cleanup "./run-migrations.sh" \
--fail-cleanup "docker-compose logs --tail 50"Quick Start & Installation
Install Loopster directly into your environment using the bootstrap installer or build with CMake:
One-Line Automated Bootstrap
curl -sL https://raw.githubusercontent.com/joshuacox/loopster/refs/heads/main/bootstrap.sh | bashManual CMake & CPack Build
git clone https://github.com/joshuacox/loopster.git
cd loopster
cmake .
make
sudo make install
# Or generate .deb and .tar.gz packages:
cpackEngineered for Resilience
Worker & Test Decoupling
Separate what does the work (-l/--loop) from what determines success (-t/--test).
Graceful Signal Trapping
Clean up reliably even if aborted early via SIGINT (Ctrl+C) or SIGTERM.
Exponential Backoff
Prevent service spamming with multiplier backoff (--backoff) and max wait limits (--max-wait).
CLI Options & Environment Variables
| Option | Default | Env Fallback | Description |
|---|---|---|---|
| -c, --count <N> | 11 | $COUNT | Maximum number of loop iterations |
| -t, --test <cmd> | echo ./test.sh | $TEST | Verification command that determines success (returns exit code 0) |
| -l, --loop <cmd> | echo ./iter.sh | $LOOP | Worker action executed on every iteration |
| -w, --wait <sec> | 0 | $WAIT | Delay (in seconds) between iterations |
| --backoff <factor> | 1 | $BACKOFF | Multiplier factor for wait time on consecutive failures (e.g. 2) |
| --max-wait <sec> | 0 | $MAX_WAIT | Upper cap on wait interval when backoff is enabled |
| --infinite | false | $INFINITE | Keep running continuously until test succeeds |
| --success-cleanup <cmd> | echo success | $SUCCESS_CLEANUP | Hook command triggered when test finally passes |
| --fail-cleanup <cmd> | echo fail | $FAIL_CLEANUP | Hook command triggered if attempts fail or loop is interrupted |
| -V, --version | - | - | Print version number and exit |
| -v, --verbose | 0 | $VERBOSITY | Increases verbosity output level with '#' squawk padding |
| --debug | false | - | Activate debug tracking mode (bash set -x) |
Standard Exit Codes for CI/CD Pipelines
Success
The test condition returned 0. Success cleanup executed and the pipeline can safely proceed.
Max Iterations Exceeded
The test did not pass within the allotted count limit. Fail cleanup ran and the process returned failure.
Interrupted / Terminated
Loopster was interrupted by SIGINT (Ctrl+C) or SIGTERM. Fail cleanup was triggered for graceful teardown.
Real-World Use Cases
1. Waiting for a Database or Microservice with Exponential Backoff
Poll an API healthcheck starting at 2s interval, doubling each time up to 30s max:
loopster \
--test "curl -fsS http://localhost:8080/healthz" \
--loop "echo 'Checking microservice readiness...'" \
--wait 2 \
--backoff 2 \
--max-wait 30 \
--count 15 \
--success-cleanup "./run-migrations.sh" \
--fail-cleanup "docker-compose logs --tail 100"2. Automated AI Prompt/Code Refinement Loop (Aider / Coding Agents)
Iteratively fix build and test issues using an agent until unit tests pass:
loopster \
--count 10 \
--loop "aider --file src/main.c -m 'fix test compilation and pass all assertions'" \
--test "make clean && make && ./test_suite" \
--success-cleanup "git checkout -b feature-success && git commit -am 'Automated fix succeeded'" \
--fail-cleanup "git checkout -b feature-failed"3. Retrying Flaky Network Deployment with Complex Piped Tests
Verify Kubernetes pod rollout status using pipes:
loopster \
--loop "kubectl rollout restart deployment/api" \
--test "kubectl get deployment api -o jsonpath='{.status.readyReplicas}' | grep -q '3'" \
--count 10 \
--wait 5 \
-vv