retry(1)

💖 NAME 💖

okay bestie, this is retry(1) from the General Commands Manual — the page for retry, aka the tool that repeats a command until a criteria is met, usually success. periodt. ✨

🦋 SYNOPSIS 🦋

retry [-v] [-h] [-u until] [-w while] command ...

🌸 DESCRIPTION 🌸

The tool repeats the given command until the command is successful, backing off with a configurable delay between each attempt. lowkey iconic.

Retry captures stdin into memory as the data is passed to the repeated command, and that captured stdin is then replayed should the command be repeated. This makes it possible to embed the retry tool into shell pipelines. 🫶

Retry captures stdout into memory, and if the command was successful stdout is passed on to stdout as normal, while if the command was repeated stdout is passed to stderr instead. This ensures that output is passed to stdout once and once only. no cap. 💅

💅 OPTIONS 💅

• -d seconds, --delay=seconds — the number of seconds to back off after each attempt. Multiple comma separated delays allow subsequent delays to be different, with the last delay repeated. 💤
• -m message, --message=message — a message to include in the notification when repeat has backed off. Defaults to the command name. 📣
• -t times, --times=times — total number of times to try the command. By default we try forever. ♾️
• -u criteria, --until=criteria — keep repeating the command until any one of the comma separated criteria is met. Options include 'success', 'true', 'fail', ’false', an integer or a range of integers. Default is 'success'. ✅
• -w criteria, --while=criteria — keep repeating the command while any one of the comma separated criteria is met. Options include 'success', 'true', 'fail', ’false', an integer or a range of integers. 🔁
• -h, --help — display this help message. 🆘
• -v, --version — display the version number. 🏷️

🔥 RETURN VALUE 🔥

The retry tool returns the return code from the command being executed, once the criteria is reached.

If the command was interrupted with a signal, the return code is the signal number plus 128. 😭

If the command could not be executed, or if the options are invalid, the status 1 is returned. 💀

🎀 EXAMPLES 🎀

Basic example: we repeat the command forever, bestie.

~$ retry --until=success -- false
retry: 'false' returned 1, backing off for 10 seconds and trying again...
retry: 'false' returned 1, backing off for 10 seconds and trying again...
retry: 'false' returned 1, backing off for 10 seconds and trying again...

^C

More complex example: each invocation of curl is retried until curl succeeds, at which point stdout is passed once and once only to the next element in the pipeline.

~$ retry -- curl --fail http://localhost/entities | \
jq ... | \
retry -- curl --fail -X POST http://localhost/resource | \
logger -t resource-init

In this example, we stagger each delay exponentially until 64 seconds, which is then repeated until interrupted.

~$ retry --until=success --delay "1,2,4,8,16,32,64" -- false
retry: false returned 1, backing off for 1 second and trying again...
retry: false returned 1, backing off for 2 seconds and trying again...
retry: false returned 1, backing off for 4 seconds and trying again...
retry: false returned 1, backing off for 8 seconds and trying again...
retry: false returned 1, backing off for 16 seconds and trying again...
retry: false returned 1, backing off for 32 seconds and trying again...
retry: false returned 1, backing off for 64 seconds and trying again...
retry: false returned 1, backing off for 64 seconds and trying again...
retry: false returned 1, backing off for 64 seconds and trying again...

^C

In this example, we try three times before giving up.

~$ retry --times=3 -- false
retry: false returned 1, backing off for 10 seconds and trying again...
retry: false returned 1, backing off for 10 seconds and trying again...
retry: false returned 1, giving up.

🌈 AUTHOR 🌈

Graham Leggett <minfrin@sharp.fm> — that's the author, bestie. 👑

okay bye bestie — this page is source/version retry-1.0.6, manual retry(1), and the original footer's date slot is blank (not me inventing a date 💀). stay slay. 💖