README
¶
The rig
The rig provides a bunch of commands to run programs and mangle their output.
Install
go get -u mrz.io/rig
Example
Use the rig to connect to some host via SSH, launch the mysql client and run a query (from STDIN) against some databases:
$ cat > preset.yaml <<EOF
command: [ssh, '{{.host}}', mysql, -D, '{{.db}}']
label: '{{.db}}'
arguments:
- { host: "foo.example.org", db: "foo" }
- { host: "bar.example.org", db: "bar" }
EOF
$ echo 'SELECT 1 AS one, 2 AS two;' | rig report preset.yaml
# output:
# foo PID 1001 is `ssh foo.example.org mysql -D foo`
# bar PID 1002 is `ssh bar.example.org mysql -D bar`
# foo finished after 0.01s
# bar finished after 0.01s
# foo one two
# foo 1 2
# bar one two
# bar 1 2
Format previous output as an ASCII table:
$ rig replay | rig render table
# output:
# foo PID 1001 is `ssh foo.example.org mysql -D foo`
# bar PID 1002 is `ssh bar.example.org mysql -D bar`
# foo finished after 0.01s
# bar finished after 0.01s
# foo one two
# foo ----------
# foo 1 2
# bar one two
# bar ----------
# bar 1 2
Commands, concepts and usage
report/stream
rig report runs programs and print their STDOUT and STDERR only when they
finish, ensuring that lines produced by different programs don't mix. A copy of
the output is also stored in ~/.rig for later use with rig replay unless
--no-store is used.
rig stream runs programs and print their STDOUT and STDERR immediately as
they are produced. Stream mode is more suitable for "water hose" programs like
tail.
Presets
rig report and rig stream find the programs to run in "preset" files given
as positional arguments. Presets are YAML files that describe the command line
of a program, an optional array of dictionaries of arguments, plus a label.
When a preset has arguments, an instance of the program is run for each
argument dictionary, command and label are parsed as Go templates and
executed against the arguments.
Programs defined in the same preset are run in sequence, while programs defined in different presets are run in parallel; this is merely a gimmick to avoid starting too many instances of potentially taxing programs at the same time by mistake.
Use the --fearless option to run all programs in parallel.
STDIN > rig > STDOUT
The report and stream commands are meant to be used in shell pipelines, and
can be understood as tools to fan out the STDIN stream to one or more programs
and join their STDOUT back to one single stream as the rig's own STDOUT.
+---[ prog1 ]---+
| |
STDIN >-----+---[ prog2 ]---+-----> STDOUT
| |
+---[ prog3 ]---+
STDIN is treated as a Go template: each program can read a copy of it after
arguments have been replaced; pass --no-template to disable this behaviour.
The label from the preset is used as a prefix for each program's STDOUT and
STDERR's line, followed by the string provided as --separator. This behaviour
can be disabled with --no-labels or --no-stderr-labels.
replay
rig replay prints STDOUT and STDERR of the last rig report command and
supports all the options of rig report that affect the output (--separator,
--no-labels and --no-stderr-labels).
render table
rig render table reads STDIN and renders it as an ASCII table, assuming it
looks like the output of rig report: lines prefixed by a label, followed by
--separator, followed by the actual program's output.
Directories