arx: Archive execution tool.

SYNOPSIS
       arx ... (-h|-[?]|--help)? ...
       arx shdat (-b <size>)? (-o <output file>)? < input
       arx shdat (-b <size>)? (-o <output file>)? <input file>+
       arx tmpx <option,archive>* (//+ <command> (//+ <option,archive>*)?)?

DESCRIPTION
       The arx tool automates a common task in the world of operations automa‐
       tion: packing code, sending it to a remote machine, unpacking in a tem‐
       porary  directory,  running a task therein and then removing the tempo‐
       rary directory.  One might do this when setting up a moderately compli‐
       cated back-up script, installing a new version of nginx or even just to
       run jobs across ones infrastructure.

       The arx tool has no in-built notion of  remote  connections  or  server
       clusters;  all automation is captured as Bourne compatible scripts that
       use a small number of UNIX utilities in  a  broadly  portable  way.  At
       present, the utilities used are sed, tr, date, head, and tar. The calls
       to tar sometimes use -j and -z; these calls to tar may result in  calls
       to bzip2 and gzip. Scripts have been tested with dash and the GNU tools
       as well as the sh and tools that are part of busybox.

       The tmpx subcommand of arx offers a variety  of  options  for  bundling
       code  and  a  task to run. The shdat subcommand exposes the lower-level
       functionality of encoding binary data in a shell  script  that  outputs
       that  binary  data, using HERE documents and some odd replacement rules
       for nulls.

       Scripts generated by tmpx and shdat may be fed to sh over STDIN to exe‐
       cute  them.  This  can  be helpful when using ssh and sudo to set up an
       execution context; for example:

       arx tmpx ... | ssh user@host.com sudo sh

       For all subcommands, when options overlap in their effect -- for  exam‐
       ple,  setting  the  output with -o -- the rightmost option takes prece‐
       dence.  Whenever -h, -? or --help is present on the command line,  help
       is displayed and the program exits.

       When  paths  are  specified on an arx command line, they must be quali‐
       fied, starting with /, ./ or ../. This simplifies the command line syn‐
       tax, overall, without introducing troublesome ambiguities.

TMPX
       The tmpx subcommand bundles together archives, environment settings and
       an executable or shell command in to a  Bourne-compatible  script  that
       runs  the  command or executable in a temporary directory, after having
       unpacked the archives and set the environment.

       Any number of file path arguments may be specified; they will be inter‐
       preted as tar archives to include in bundled script. If no archives are
       specified, or - is given, then STDIN will be included.

       The temporary directory created by the script  is  different  for  each
       invocation,  with  a  name of the form /tmp/tmpx.<timestamp>.<pid>. The
       timestamp used is a UTC, ISO 8601 format timestamp.  One  happy  conse‐
       quence  of  this  is that earlier jobs sort ASCIIbetically before later
       jobs. After execution, the temporary  directory  is  removed  (or  not,
       depending on the -rm[10!_] family of options).

          -rm0, -rm1, -rm_, -rm!

                 By  default,  the  temporary  directory created by the script
                 will be deleted no matter the exit status status of the task.
                 These options cause a script to be generated that deletes the
                 temporary directory only on success, only on failure,  always
                 (the default) or never.

          -b <size>

                 Please  see  the  documentation  for this option, shared with
                 shdat, below.

          -o <path>

                 By default, the generated script is sent to STDOUT. With  -o,
                 output is redirected to the given path.

          -e <path>

                 Causes  the  file  specified to be packaged as the task to be
                 run. A binary executable, a Ruby script or  a  longish  shell
                 script all fit here.

       In  addition to these options, arguments of the form VAR=VALUE are rec‐
       ognized as environment mappings and stored away in the  script,  to  be
       sourced on execution.

       Without  -e,  the tmpx subcommand tries to find the task to be run as a
       sequence of arguments delimited by a  run  of  slashes.  The  following
       forms are all recognized:

       arx tmpx  ...some args... // ...command...
       arx tmpx  ...some args... // ...command... // ...more args...
       arx tmpx // ...command... // ...some args...

       The  slash  runs  must  have the same number of slashes and must be the
       longest continuous runs of slashes on the  command  line.  The  command
       will be included as is in a Bourne shell script.

SHDAT
       The  shdat subcommand translates binary data in to a shell script which
       outputs the binary data. The data is encoded in HERE documents in  such
       a  way that data without NULs is not changed and that data with NULs is
       minimally expanded: about 1% for randomish data  like  compressed  tar‐
       balls and about 10% in pathological cases.

       The  shdat  subcommand  can be given any number of paths, which will be
       concatenated in the order given. If no path is given, or if - is given,
       then STDIN will be read.

          -b <size>

                 The  size  of data chunks to place in each HERE document. The
                 argument is a positive integer followed by suffixes  like  B,
                 K,  KiB,  M and MiB, in the manner of dd, head and many other
                 tools. The default is 4MiB.  This is unlikely to make a  dif‐
                 ference for you unless the generated script is intended to be
                 run on a memory-constrained system.

          -o <path>

                 By default, the generated script is sent to STDOUT. With  -o,
                 output is redirected to the given path.

EXAMPLES
       # Installer script that preserves failed builds.
       git archive HEAD | bzip2 | arx tmpx -rm0 // make install > go.sh
       # Now install as root; but don't log in as root.
       cat ./go.sh | ssh joey@hostname sudo /bin/sh

       # Variation of the above.
       git archive HEAD | bzip2 | arx tmpx -rm0 -e ./build-script.py

       # Bundle an instance of an application with DB credentials and run it.
       arx tmpx -rm! ./app.tbz ./stage-info.tgz // rake start | ssh ...

       # Get dump of linking info for build that works here but not there.
       arx tmpx ./server-build.tgz LD_DEBUG=files // ./bin/start | ssh ...

       # Test out Cabal source distribution of this package:
       arx tmpx // 'cd arx-* && cabal configure && cabal build' // \
                -rm0 ./dist/arx-0.0.0.tar.gz | sh

BUGS
       The  command  line parser offers no hints or help of any kind; it fails
       with the simple message "argument error". The two most common  mistakes
       I make are:

       · Not qualifying paths with /, ./ or ../.

       · Not specifying a subcommand (tmpx or shdat).