recur for Mac

recur is a command-line tool that runs a single command repeatedly until it succeeds or no more attempts are left. It implements optional exponential backoff with configurable jitter. It lets you write the success condition in Starlark.

Installation

Prebuilt binaries

Prebuilt binaries for FreeBSD (amd64), Linux (aarch64, riscv64, x86_64), macOS (arm64, x86_64), NetBSD (amd64), OpenBSD (amd64), and Windows (amd64, arm64, x86) are attached to releases.

Homebrew

You can install recur from Homebrew on macOS and Linux:

Go

Install Go, then run:

Build requirements Go 1.22 Task (go-task) 3.28

Usage

Command-line interface

Duration arguments take Go duration strings; for example, 0, 100ms, 2.5s, 0.5m, or 1h. The value of -j/--jitter must be either a single duration or two durations joined with a comma, like 1s,2s or 500ms, 0.5m.

If the maximum allowed delay (-m/--max-delay) is shorter than the constant delay (-d/--delay), recur will automatically increase the maximum delay to match the constant delay. Use the option -m/--max-delay after -d/--delay if you want a shorter maximum delay.

The additional random delay (-j/--jitter) and the maximum allowed delay do not interact. Jitter is not capped by the maximum delay and does not count towards it.

The following recur options run the command foo --config bar.cfg indefinitely. Every time foo exits, there is a delay that grows exponentially from two seconds to a minute. The delay resets back to two seconds if the command runs for at least five minutes.

recur exits with the last command's exit code unless the user overrides this in the condition. When the command is not found during the last attempt, recur exits with code 127. recur exits with code 124 on timeout and 255 on internal error. [!NOTE] The option -f/--forever is deprecated because of the ambiguity of "forever". (recur --forever still tries until success unless you change the success condition.) -f/--forever will remain available. It is not recommended for new usage: use -u/--unlimited instead.

Standard input

By default, the command run by recur inherits its standard input). This means that if standard input is a terminal, every attempt can read interactively from the terminal. If standard input is a pipe or redirected file, the data is consumed on the first attempt; later attempts see an immediate EOF.

To feed the command the same data on each attempt, use the -I/--replay-stdin option. With this option, recur reads its entire stdin into memory and replays it on each attempt.

Because the data is buffered in memory, --replay-stdin is not recommended for very large inputs.

Standard output and standard error