Command-line Reference

Usage

Usage:
    pave v0.68 - (C) 2012-2013 Mike Miller.
    License: GNU GPLv3+
    Yet another config and deployment tool, leveraging fabric.

    pave [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -b, --brace-exp       Use string.format-style brace expansion instead of
                        printf.
  -c STR, --command=STR
                        Override pavefile tasks with an ad hoc command.
  -f NAME, --filename=NAME
                        Use an input file besides ./pave.yml.
  -i, --interactive     Stop and ask whether to run each task group.
  -j #, --jobs=#        Run pave tasks in parallel with the given pool size.
  -o N V, --option=N V  Override a pavefile option.
  -s #, --select=#      Select task groups to run, instead of all. (0-based
                        slice syntax, # or #:#).
  -S, --skel            Output a "skeleton" pavefile to get started on.
  -t T, --target=T      Override targets with this host or group.  Multiple
                        accepted.
  -q, --quiet           Silence routine output, allowing warnings and errors.
                        Overrides verbose.
  -v  N V, --var= N V   Override a pavefile variable.
  -V, --verbose         Enable overwhelmingly verbose debugging output.
  --color=CHOICE        Message coloring/icons ('auto', 'on', 'off').
  --crypt               Ask for a password, print its hash and exit. For use
                        with users: module in the pavefile.
  --speak               Talk to me, holmes.
  --test                Test mode: parse and validate, skip execution.

Exit Status Codes

Pave returns standard status codes from sysexits.h:

EX_OK           0       # successful termination
EX_USAGE        64      # command line usage error
EX_DATAERR      65      # data format error
EX_NOINPUT      66      # cannot open input
EX_NOUSER       67      # addressee unknown
EX_NOHOST       68      # host name unknown
EX_UNAVAILABLE  69      # service unavailable
EX_SOFTWARE     70      # internal software error
EX_OSERR        71      # system error (e.g., can't fork)
EX_OSFILE       72      # critical OS file missing
EX_CANTCREAT    73      # can't create (user) output file
EX_IOERR        74      # input/output error
EX_TEMPFAIL     75      # temp failure; user is invited to retry
EX_PROTOCOL     76      # remote error in protocol
EX_NOPERM       77      # permission denied
EX_CONFIG       78      # configuration error

Password “Escape Hatch”

In addition to the standard keyboard interrupt Ctrl+C, if a password is requested (via the pavefile) at the command line the process can be escaped by giving two empty passwords in a row. The program will exit.

Option Path Syntax

To override pavefile options on the fly, “option path” syntax is used, which describes the hierarchy in a compact manner. This syntax is used for command-line (-o|--option) overrides. Inside the pavefile, however, path separators (/) are not supported; indentation is used instead.

main:           # pavefile
    jobs: 1

equals:

/main/jobs 1    # command-line

Task Selection

Selection of a subset of tasks (or “task groups”) can be done with the -s/--select option, and uses Python-style “slicing” syntax.

Indexes are zero-based, and use negative numbers to specify items from the end. Start and stop indexes, and/or step values may be given and are separated with the colon : character. If a part is omitted, it defaults to start, end, or a step of 1.

Below is a visualization that may be helpful. Given a list of tasks, the task index marks the beginning (left or top) edge:

 +---+---+---+---+---+              # horizontal
 | T | T | T | T | T |
 +---+---+---+---+---+
 0   1   2   3   4  (5=length)
-5  -4  -3  -2  -1

- TASK1, index  0  or  -5           # vertical
- TASK2, index  1  or  -4
- TASK3, index  2  or  -3
- TASK4, index  3  or  -2
- TASK5, index  4  or  -1

Example:

pave -s 0               # the first task, group only
pave -s -2              # the second to last task, group
pave --select 10:20     # task groups 10-19
pave --select :6:2      # every other task from the first six

Further discussion can be found here: