.\" Text automatically generated by txt2man
.TH retry  "1" "retry-1.0.4" ""


.SH NAME
\fBretry \fP- Repeat command until a criteria is met, usually success.
\fB
.SH SYNOPSIS
.nf
.fam C
\fBretry\fP [\fB-v\fP] [\fB-h\fP] [\fB-u\fP \fIuntil\fP] [\fB-w\fP \fIwhile\fP] \fIcommand\fP \.\.\.

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION

The tool repeats the given \fIcommand\fP \fIuntil\fP the \fIcommand\fP is successful,
backing off with a configurable delay between each attempt.
.PP
Retry captures stdin into memory as the data is passed to the repeated
\fIcommand\fP, and this captured stdin is then replayed should the \fIcommand\fP
be repeated. This makes it possible to embed the \fBretry\fP tool into shell
pipelines.
.PP
Retry captures stdout into memory, and if the \fIcommand\fP was successful
stdout is passed on to stdout as normal, \fIwhile\fP if the \fIcommand\fP was
repeated stdout is passed to stderr instead. This ensures that output
is passed to stdout once and once only.
.SH OPTIONS
.TP
.B
\fB-d\fP seconds, \fB--delay\fP=seconds
The number of seconds to back off
after each attempt.
.TP
.B
\fB-m\fP message, \fB--message\fP=message
A message to include in the notification
when repeat has backed off. Defaults to the
\fIcommand\fP name.
.TP
.B
\fB-t\fP times, \fB--times\fP=times
The number of times to \fBretry\fP
the \fIcommand\fP. By default we try forever.
.TP
.B
\fB-u\fP criteria, --\fIuntil\fP=criteria
Keep repeating the \fIcommand\fP \fIuntil\fP any one
of the comma separated criteria is met.
Options include 'success', 'true', 'fail',
\(cqfalse', an integer or a range of integers.
Default is 'success'.
.TP
.B
\fB-w\fP criteria, --\fIwhile\fP=criteria
Keep repeating the \fIcommand\fP \fIwhile\fP any one
of the comma separated criteria is met.
Options include 'success', 'true', 'fail',
\(cqfalse', an integer or a range of integers.
.TP
.B
\fB-h\fP, \fB--help\fP
Display this help message.
.TP
.B
\fB-v\fP, \fB--version\fP
Display the version number.
.SH RETURN VALUE
The \fBretry\fP tool returns the return code from the
\fIcommand\fP being executed, once the criteria is reached.
.PP
If the \fIcommand\fP was interrupted with a signal, the return
code is the signal number plus 128.
.PP
If the \fIcommand\fP could not be executed, or if the options
are invalid, the status 1 is returned.
.SH EXAMPLES
In this basic example, we repeat the \fIcommand\fP forever.
.PP
.nf
.fam C
        ~$ 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

.fam T
.fi
In this more complex example, each invocation of curl is
retried \fIuntil\fP curl succeeds, at which point stdout is
passed once and once only to the next element in the
pipeline.
.PP
.nf
.fam C
        ~$ retry curl --fail http://localhost/entities | \\ 
        jq \.\.\. | \\ 
        retry curl --fail -X POST http://localhost/resource | \\ 
        logger -t resource-init

.fam T
.fi
.SH AUTHOR
Graham Leggett <minfrin@sharp.fm>