rerun - Take your shell scripts and turn them into powerful full featured management utilities with no extra programming.
rerun [-h][-v][-V][--version] [-M <dir>] [module:[command [options]]]
You are never going to get rid of bash scripts entirely. Rerun creates a nice interface for users and a framework for the scripters that makes you look good and a better team player.
Rerun is a simple command runner that turns loose shell scripts into modular automation. Rerun will help you organize your implementation into well defined command interfaces. Collections of management modules can be archived and delivered as a single executable to facilitate team hand offs. Using the "stubbs" module, rerun will even facilitate developing modules using a test-driven development practice.
What does rerun give you?
- A framework to script writing that does things like generate option parsers
- Command completion in your bash shell
- Packaging in rpm/deb or standalone
- Logging formats with levels and ansi color
- Nice user experience
- Simple to use test framework
- Build process you can hook into your CI loop
Rerun provides two modes of operation:
- Listing: Rerun lists modules and commands. Listing information includes name, description and command line usage syntax.
- Execution: Rerun provides option processing (possibly defaulting unspecified arguments) and executes a script for the specified module command.
For the module developer, rerun is a trivial framework following simple conventions that easily fit in a shell environment. Rerun includes a module development tool called "stubbs" that helps create and evolve rerun modules. Stubbs contains commands to automate option processing code, metadata definition and unit testing.
rerun implements a simple dispatching mechanism to look up named
commands and execute them. Commands are logically named and
have a corresponding script.
Commands reside in a module and can have named parameters called options. Each option is named, described and can also be defined to use a default value or say whether it is required or not.
Rerun modules can also declare metadata describing name, description and other aspects of each command. Rerun makes use of this metadata to support a listing mode, a feature where modules and command usage are summarized for end users.
See the project wiki for additional documentation including:
: Print help and usage then exit.
: Module library directory path.
: Execute command in verbose mode.
rerun and command in verbose mode.
: Print the rerun version.
For command line syntax and example usage execute
rerun using the
$ ./rerun --help _ __ ___ _ __ _ _ _ __ | '__/ _ \ '__| | | | '_ \ | | | __/ | | |_| | | | | |_| \___|_| \__,_|_| |_| Version: v0.1. License: Apache 2.0. Usage: rerun [-h][-v][-V][--version] [-M <dir>] [module:[command [options]]] Examples: | $ rerun | => List all modules. | $ rerun waitfor | => List all waitfor commands. | $ rerun waitfor:http --url http://google.com | => Execute the waitfor:http command. | $ rerun -M /var/rerun waitfor:http | => Execute the waitfor:http command found in /var/rerun
rerun will list existing modules:
$ rerun waitfor: "wait for condition."
To list the commands available from the 'waitfor' module:
$ rerun waitfor http: "wait for url to become available" --url <>: "the url to check" --interval <30>: "the time interval" ping: "wait for ping response from host" --host <"">: "host to check" --interval <30>: "the time interval"
The listing consists of info about command options including default values if they were described with option metadata.
Options that declare a default value are shown with a string between the "<>" characters.
For example, notice how "--interval" option shows
The "30" is the default value assigned to the "--interval" option.
See the "Environment" section below to learn about the
RERUN_MODULES environment variable. This variable
specifies the directory where rerun modules exist.
If you are a Bash shell user, be sure to source the
It provides listing via the tab key.
rerun and then the tab key. The shell will generate
a list of existing modules.
$ rerun[TAB][TAB] waitfor
Rerun shows there is a module named "waitfor" installed.
Typing the tab key again will show the commands inside the "waitfor" module:
$ rerun waitfor: [TAB] http ping
In this case, two commands are found and listed. Press tab again and choose a command. After accepting a command, typing the tab key will show arguments.
$ rerun waitfor:ping -[TAB] --host --interval
waitfor:ping command accepts options (--host <> --interval <>).
Commands are executed by stating the module,
command and possibly options. The basic usage form is
rerun module:command [options]".
To run the "ping" command in the waitfor module, type:
$ rerun waitfor:ping --host localhost OK: localhost is pingable.
The outputed string "OK: localhost is pingable." is the printed result. In this example, "30" is the interval option's default value as defined in the module metadata.
Command options are passed after the "module:command" string.
Tell waitfor to wait for the url, "http://google.com" by specifying
--url <> option:
$ rerun waitfor:http --url http://google.com OK
If the 'waitfor' module is stored in
/var/rerun, then the command usage
$ rerun -M /var/rerun waitfor:ping OK: localhost is pingable.
An archive contains all the rerun modules you need (you might have a library of them) and gives you the same exact interface as rerun,... all in one file!
Specifically, an archive is a set of modules
rerun itself packaged into a self extracting
script (by default in a file named "rerun.sh").
Archives can be useful if you want
to share a single self contained executable that contains all the needed modules.
Run an archive script like you would run
You can execute an archive via
bash like so:
$ bash rerun.sh <module>:<command> --your options
If the execute bit is set, invoke the archive directly.
Here the archive is executed without arguments which causes the archive to list the modules contained within it.
$ ./rerun.sh waitfor: "wait for a condition" - 1.0.0 . . listing output ommitted
Note, ".sh" is just a suffix naming convention for a self-extracting script. The archive file can be named anything you wish.
waitfor:http command in the archive:
$ ./rerun.sh waitfor:http --url http://google.com . .
stubbs:archive for further information about creating and
understanding rerun archives.
A rerun module assumes the following structure:
<MODULE> ├── commands │ ├── cmdA (directory for cmdA files) │ │ ├── metadata (command metadata) │ │ ├── script (command script) │ │ └── options.sh (option parsing script) │ └── cmdB │ ├── metadata │ ├── script │ └── options.sh ├── metadata (module metadata) └── lib
Rerun's internal dispatch logic uses the directory layout described above to find and execute scripts for each command.
The metadata file format uses line separated KEY=value pairs to define module attributes. The module metadata file declares two properties:
- NAME: Declare name displayed to user.
- DESCRIPTION: Brief explanation of use.
For example, a module named
waitfor is named
and described in a file called
NAME="waitfor" DESCRIPTION="wait for a condition"
Command metadata is described in a file called
Here's the command metadata for the "ping" command:
NAME="ping" DESCRIPTION="wait for ping response from host"
Options are described in a file called
Beyond just NAME and DESCRIPTION, options can also declare:
- ARGUMENTS: Does the option take an argument.
- REQUIRED: Is the option required.
- DEFAULT: Sensible value for an option default
Here's the metadata describing the option named "host":
NAME=host DESCRIPTION="the host to ping" ARGUMENTS=true REQUIRED=true DEFAULT=
And for the --interval option
NAME=interval DESCRIPTION="the interval to wait in seconds" ARGUMENTS=true REQUIRED=true DEFAULT=30
Combining the examples above into the layout described earlier the "waitfor" module along with its commands "http" and "ping" are illustrated here:
waitfor ├── commands │ └── http (directory for http command files) │ ├── metadata (command metadata) │ ├── options.sh (option parsing script) │ └── script (command script) ├── lib │ └── functions.sh (module function library) ├── metadata (module metadata) ├── options (module options) │ ├── url (--url option) │ │ └── metadata (declares metadata for "url" option) │ └── interval (--interval option) │ └── metadata (declares metadata for "interval" option) └── tests └── http-1-test.sh (unit tests for http)
: Path to directory containing rerun modules.
If RERUN_MODULES is not set, it is defaulted
relative to the location of the rerun executable.
: Set 'true' if you want ANSI text effects. Makes
labels in text to print bold in the console.
Syntax errors will also print bold.
To create modules, see stubbs.
: All commands executed successfully
: One or more commands failed
: Unknown error case
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
The rerun source code and all documentation may be downloaded from https://github.com/rerun/rerun/.